Deploying Docker container#
To be able to deploy and run the OpenQuake Engine Docker container you need at least Docker version 1.10.
A basic knowledge about Docker and how this kind of application containers work is also required. For more information about operating system support (which includes Linux, macOS and specific versions of Windows) and on how to install Docker, please refer to the official Docker website.
Features provided#
Each container includes:
Python 3.11 from official docker image
Python dependencies (numpy, scipy, h5py…)
OpenQuake Engine and Hazardlib
The
oqcommand line toolThe OpenQuake WebUI and API server (by default listening on port 8800)
Deployment#
Docker single node deployment#
Pull an image from Docker Hub (see [available-tags] (https://hub.docker.com/r/openquake/engine/tags/) ):
$ docker pull docker.io/openquake/engine[:TAG]
Headless mode#
This modality is recommended when only the WebUI or the API server is used (for example as the backend for the OpenQuake QGIS plugin).
$ docker run --name <containername> -d -p 8800:8800 openquake/engine:nightly "oq webui start"
Then you can connect to http://localhost:8800 to be able to access the WebUI or the API server.
You can stop and start again your container with the following commands:
$ docker stop <containername>
$ docker start <containername>
TTY mode#
This modality provides the same features as the headless mode plus the ability to drive the OpenQuake Engine via the oq command on a terminal.
$ docker run --name <containername> -t -i -p 8800:8800 openquake/engine:nightly bash
The container prompt will appear, here you play with the oq shell command.
[openquake@b318358ee053 ~]$ oq --version
3.20.0
After you have restarted you container (same commands as the headless mode) you can re-attach the container shell using:
$ docker attach <containername>
[openquake@b318358ee053 ~]$
Remove a container or an image#
To destroy a container, type:
$ docker rm <containername>
To remove its image:
$ docker rmi openquake/<imagename>[:TAG]
You can print the list of containers and images using $ docker ps -a and $ docker images. For more details please refer to the official Docker documentation.
Docker advanced options#
Environment Variables#
The Openquake image uses several environment variables.
LOCKDOWN
This environment variable is required and set to True to enable the webui authentication. The default value is False, and it can also be undefined if the webui authentication is not necessary.
$ docker run -e LOCKDOWN=True openquake/engine:nightly "oq webui start 0.0.0.0:8800 -s"
If you don’t set any other environment variables the default values for admin login, password and email are: ‘admin’, ‘admin’, ‘admin@example.com’.
OQ_ADMIN_LOGIN
This variable defines the superuser admin login in the webui.
OQ_ADMIN_PASSWORD
This environment variable sets the superuser admin password for webui.
OQ_ADMIN_EMAIL
This environment variable sets the superuser admin email for webui.
WEBUI_PATHPREFIX
This variable ovverides the default prefix path (/engine) for the webui.
$ docker run --name openquake -p 127.0.0.1:8800:8800 -e LOCKDOWN=True -e OQ_ADMIN_LOGIN=example -e OQ_ADMIN_PASSWORD=example -e OQ_ADMIN_EMAIL=login@example.com openquake/engine:nightly "oq webui start 0.0.0.0:8800 -s"
This example runs a container named openquake using the openquake/engine:nightly image and sets the value for the environment variables.
This binds port 8800 of the container to TCP port 8800 on 127.0.0.1 of the host machine, so the webui is reachable from the host machine using the url: http://127.0.0.1:8800/engine.
$ docker run --name openquake -p 127.0.0.1:8080:8800 -e LOCKDOWN=True -e WEBUI_PATHPREFIX='/path' openquake/engine:nightly "oq webui start 0.0.0.0:8800 -s"
This example runs a container named openquake using the openquake/engine:nightly image and sets the value for the environment variables.
This binds port 8800 of the container to TCP port 8080 on 127.0.0.1 of the host machine, so the webui is reachable from host machine using the url: http://127.0.0.1:8080/path
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