Examples
This section will contain some example run configurations for the Ignition Docker image. Review these examples to learn a bit more about how to run and configure the Ignition Docker image, as well as some typical best practices.
Deploying an Ephemeral Gateway for Testing
The run statement below will launch a container in detached mode -d
, publishing port 9088
from the host to port 8088
in the container. The container will be named ignition-test
and use the 8.1.7
image. Finally, the runtime arguments provided will set the Gateway name to docker-test
with public address of localhost
on HTTP port 9088
and HTTPS port 9043
.
docker run -d -p 9088:8088 --name ignition-test inductiveautomation/ignition:8.1.7 \
-n docker-test -a localhost -h 9088 -s 9043
Preserving Gateway State
When using containers, it is common for stateful applications (such as the Ignition Gateway) to leverage volumes to persist that state across image updates, container remove/create cycles, etc. This can be done by applying a named volume to the /usr/local/bin/ignition/data
path within the container. This is especially important if you need to make a change to your container configuration. Since container configurations are immutable, the only way to change it is to stop/remove the old container and start a new one (with a new configuration).
Similar to the above, but this time with a named volume gw-data
attached to /usr/local/bin/ignition/data
within the container. If the volume doesn't already exist, it will be created automatically. Note the additional --pull
option to make sure that the latest
tag is always pulled before running--without this, the latest
tag is only pulled if one isn't already present on your system.
docker run -d -p 9088:8088 --name ignition-test \
-v gw-data:/usr/local/bin/ignition/data \
--pull always inductiveautomation/ignition:latest \
-n docker-test -a localhost -h 9088 -s 9043
By using named volumes, you're now able to stop and remove the ignition-test
container and create a new one with a different configuration. As long as you attach your volume, your gateway will start up with all of your tags and projects in their previous state.
Preserving KeyStores
The following feature is new in Ignition version
8.1.12
Click here to check out the other new features
Starting in 8.1.12, the following KeyStores are also preserved across image updates.
Gateway Network Certificate
This PKCS #12 KeyStore contains the certificate and private key used for gateway network communications, and is created automatically on Gateway startup if not present. Typically this is maintained independently on a per-installation basis to avoid issues from operations such as gateway backup restorations. The situation within a container is somewhat different, and it is usually preferable to track this KeyStore with the rest of the gateway state preserved by a volume. Docker image now redirects, via sym-link, Gateway Network KeyStore creation from webserver/metro-keystore
to data/local
. This will allow the underlying image for the container to be upgraded without generating a new Gateway Network certificate (thus breaking existing approved certificates and connections).
SSL Configuration
When SSL is enabled on a Gateway, ssl.pfx
is created as a PKCS #12 KeyStore with the private key, server certificate, and root/intermediate CA certificates. This file is automatically read by the Gateway on startup to enable SSL. Similar to the Gateway Network Certificate, this resides outside of the data/
volume since it is intended to persist across a gateway restore operation. Docker image now redirects, via sym-links, SSL KeyStore creation from webserver/ssl.pfx
and webserver/csr.pfx
to data/local
. This allows a Docker container's SSL configuration to persist via the data volume without relying on extra bind-mounts. Disabling SSL now recognizes the presence of sym-links when removing the KeyStore and removes the final target of the link, leaving the sym-link in place.
Automating the Restore of a Gateway Backup
The following feature is new in Ignition version
8.1.8
Click here to check out the other new features
You can automate the restore of a gateway backup on first-launch of your gateway container. This allows for having a new Ignition Gateway restore to a known initial state automatically, without waiting for the commissioning steps.To leverage this feature, bind-mount a gateway backup into the container and then use the -r
runtime argument to specify the location and command the restore. Additionally, supply the ACCEPT_IGNITION_EULA=Y
environment variable to accept the Ignition EULA (see the Licensing section below) and bypass that gateway commissioning step.
docker run -d -p 9088:8088 --name ignition-test \
-v gw-data:/usr/local/bin/ignition/data \
-v /path/to/gateway.gwbk:/restore.gwbk \
-e ACCEPT_IGNITION_EULA=Y \
inductiveautomation/ignition:8.1.7 \
-n docker-test -a localhost -h 9088 -s 9043 \
-r /restore.gwbk
Automate the Commissioning of a Fresh Gateway
The following feature is new in Ignition version
8.1.8
Click here to check out the other new features
You can automate the commissioning steps that normally require manual user interaction on the very first launch of the Ignition Gateway. By supplying specific environment variables , you can seed the commissioning steps with the required information to start the rest of the Gateway automatically.
docker run -d -p 9088:8088 --name ignition-test \
-e ACCEPT_IGNITION_EULA=Y \
-e GATEWAY_ADMIN_PASSWORD=password \
-e IGNITION_EDITION=standard\
inductiveautomation/ignition:8.1.8 \
-n docker-test
Customizing JVM/Wrapper/Gateway Arguments on Container Launch
This example shows how to leverage the supplemental JVM/wrapper args feature.
docker run -d -p 9088:8088 --name args-test \
-e ACCEPT_IGNITION_EULA=Y \
-e GATEWAY_ADMIN_PASSWORD=changeme \
-e IGNITION_EDITION=standard\
inductiveautomation/ignition:8.1.8 \
-n args-test \
-- wrapper.java.initmemory=256 -Dignition.allowunsignedmodules=true \
-XX:MaxGCPauseMillis=200
The following feature is new in Ignition version
8.1.10
Click here to check out the other new features
The following demonstrates how to enable the gateway's Resolve Host Names and Use Proxy Forwarded Headers settings by modifying the entries in the gateway.xml
:
docker run -d -p 9088:8088 --name ignition-test inductiveautomation/ignition:8.1.10 -n docker-test -a localhost -h 9088 -s 9043 \
-- gateway.resolveHostNames=true gateway.useProxyForwardedHeader=true
Using Docker Compose
A common practice is to leverage Docker Compose to start your container and bundle the configuration with other services, such as databases and MQTT brokers. Below is an example docker-compose.yml
file that you can create inside of a new, empty folder. The example below incorporates many of the configurability features mentioned in the various sections above.
# Docker Compose Example for inductiveautomation/ignition
# Compose Spec: https://github.com/compose-spec/compose-spec/blob/master/spec.md
---
services:
# Ignition Gateway
gateway:
image: inductiveautomation/ignition:8.1.8
ports:
- 9088:8088
- 9043:8043
volumes:
- gw-data:/usr/local/bin/ignition/data
# env_file: ignition.env # optionally specify variables in a file, or using `environment:` below
environment:
- ACCEPT_IGNITION_EULA=Y
- GATEWAY_ADMIN_USERNAME=admin
- GATEWAY_ADMIN_PASSWORD_FILE=/run/secrets/gateway-admin-password
- IGNITION_EDITION=standard
- TZ=America/Chicago # see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List
secrets:
- gateway-admin-password
command: >
-n docker-test
-m 1024
--
wrapper.java.initmemory=512
-Dignition.allowunsignedmodules=true
secrets:
gateway-admin-password:
file: secrets/GATEWAY_ADMIN_PASSWORD
volumes:
gw-data:
Once defined, you can bring up the solution using `docker compose` commands. See the animated example below:
