Server and WebUI#
Advanced configurations and Authentication support#
Installation with the universal installer#
The OpenQuake Engine server supports authentication provided by Django and its backends.
When installing the OpenQuake Engine with the universal installer please refer to Universal installer.
The local_settings.py file must be located under the folder openquake/server of the oq-engine repository.
For example if you clone the repository in the folder /opt/openquake/src/oq-engine/ you must place the file in /opt/openquake/src/oq-engine/openquake/server.
If you only download the install.py file and run the installation, the local_settings.py file must be located in /opt/openquake/venv/lib/python3.11/site-packages/openquake/server (replacing python3.11 with the actual python version).
Then, copy the contents of openquake/server/local_settings.py.server into openquake/server/local_settings.py.
Configure the STATIC_ROOT folder#
STATIC_ROOT is the full, absolute path to your static files folder.
Please remember to create the folder /var/www and set the ownership to the user openquake.
sudo mkdir /var/www
sudo chown -R openquake /var/www/
Configure the directory to store the server user access log#
By default, user access information is logged through the standard Django logger.
In order to write such information to a file, for instance to be digested by Fail2Ban, the variable WEBUI_ACCESS_LOG_DIR is specified in local_settings.py.
In that case the file webui-access.log will be created inside the specified directory.
Please note that the directory must be created if it does not exist yet.
Furthermore, the user openquake must own that directory.
sudo mkdir /var/log/oq-engine
sudo chown -R openquake /var/log/oq-engine
Upgrade the database to host users and sessions:
cd /opt/openquake/src/oq-engine/openquake/server
sudo -u openquake /opt/openquake/venv/bin/python3 manage.py migrate
Install fixtures for cookie consent:
cd /opt/openquake/src/oq-engine/openquake/server
sudo -u openquake /opt/openquake/venv/bin/python3 manage.py loaddata ./fixtures/0001_cookie_consent_required_plus_hide_cookie_bar.json
If the current installation requires Google Analytics, please add the GOOGLE_ANALYTICS_TOKEN to local_settings.py and install another optional fixture:
cd /opt/openquake/src/oq-engine/openquake/server
sudo -u openquake /opt/openquake/venv/bin/python3 manage.py loaddata ./fixtures/0002_cookie_consent_analytics.json
Required or optional cookies or groups of them can be added, removed or edited via the Django Admin interface.
New custom cookies can be managed similarly to what is done in openquake/server/templates/engine/includes/cookie_analytics.html.
Please refer to https://django-cookie-consent.readthedocs.io/en/latest/ for further details on how to customize cookies in Django.
Add a new local superuser:
cd /opt/openquake/src/oq-engine/openquake/server
sudo -u openquake /opt/openquake/venv/bin/python3 manage.py createsuperuser
To setup static files in Django, issue the following commands, making sure to refer to the actual folder where the engine was installed or cloned (see above):
cd /opt/openquake/src/oq-engine/openquake/server
sudo -u openquake /opt/openquake/venv/bin/python3 manage.py collectstatic
The commands must be run as the openquake user and the installation must be of kind server or devel_server.
If, for any reason, the commands are not available in the path, you can use the following syntax:
python3 -m openquake.server.manage <subcommand>
Groups support#
Users can be part of groups. Members of the same group can have access to any calculation and output produced by any member of that group; only the owner of a calculation can delete it.
Users and groups management#
Users and groups can be managed via the Django admin interface, available at /admin when LOCKDOWN is enabled.
Authentication using PAM#
Authentication can rely on system users through PAM, the Pluggable Authentication Module. To use this feature python-pam and django-pam extensions must be installed and activated. To activate them copy the contents of openquake/server/local_settings.py.pam into openquake/server/local_settings.py and upgrade the database:
cd /opt/openquake/src/oq-engine/openquake/server
sudo -u openquake /opt/openquake/venv/bin/python3 manage.py migrate
Then restart the WebUI service.
This feature is available on Linux only and the WebUI process owner must be member of the shadow group.
Mapping of unix groups isn’t supported at the moment.
Running in production#
On a production system, nginx + gunicorn is the recommended software stack to run the WebUI.
gunicorn#
gunicorn can be installed via pip in the venv of the OpenQuake engine. For example:
sudo su -
source /opt/openquake/venv/bin/activate
pip install gunicorn
deactivate
gunicorn is usually managed by the OS init system.
Please replace the value of ExecStart in the file /etc/systemd/system/openquake-webui.service with:
WorkingDirectory=/opt/openquake/src/oq-engine/openquake/server
ExecStart=/opt/openquake/venv/bin/gunicorn --bind 127.0.0.1:8800 --workers 4 --timeout 1200 wsgi:application
gunicorn must be started in the openquake/server directory with the following syntax:
gunicorn -w N wsgi:application
where N is the number of workers. We suggest N = 4.
nginx#
gunicorn does not serve static content itself thus a frontend like nginx is needed.
Please refer to the nginx installation istructions for your operating system.
nginx must be configured to act as a reverse proxy for gunicorn and to provide static content (see documentation).
When the reverse proxy is configured, add the following to openquake/server/local_settings.py:
USE_REVERSE_PROXY = True
Getting help#
If you need help or have questions/comments/feedback for us, you can subscribe to the OpenQuake users mailing list: https://groups.google.com/g/openquake-users