Docker Image

Runtime Arguments

The following are accepted by the container as runtime arguments.  Options should be followed by a value, flags are stand-alone.  Note that these arguments are passed after the image name in a Docker Run statement.

Options

* - Specify Public address/HTTP/HTTPS ports together, all three must be specified

Flags

Supplemental JVM and Wrapper Arguments

Gateway Arguments

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

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

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

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

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:

Licensing

The Inductive Automation software contained in this Docker container image is licensed under the terms of the Inductive Automation Software License Agreement.

By passing the value ACCEPT_IGNITION_EULA=Y, you agree that your use of Inductive Automation software running in this Docker container image is governed by the terms of the Inductive Automation Software License Agreement.

All third party software (whether open or closed) running in this Docker container image is licensed as indicated in this Docker Hub “License” section or in the container itself, usually as a NOTICE or LICENSE file. You agree to comply with any relevant licenses for third party software contained in this Docker container image.