Skip to main content
Version: 8.1

Docker Image

The Ignition Platform offers a container image for use on popular container runtimes such as Docker. You can find the image on Docker Hub at https://hub.docker.com/r/inductiveautomation/ignition. Our official image is a Linux container, based on Ubuntu Linux.

New in 8.1.16

Ignition's Docker Image build is now multi-architecture and supports linux/amd64, linux/arm64, and linux/arm/v7. Users can docker pull inductiveautomation/ignition and get an image that automatically matches their system architecture.

Getting Started​

In order to get started with Ignition running as a container, you'll need a container runtime. Docker Desktop, available for Windows and macOS, includes both the Docker Engine container runtime as well as container tooling and supporting tools such as Docker Compose. If you are running Linux, you'll need to download and install the container runtime and tools such as Docker Compose individually. Guidance for the installation and configuration of Docker (on all platforms) are available here: Get Docker

Configuration​

Various aspects of the Ignition Gateway can be configured through the use of either command-line arguments to the container, or environment variables. This section will detail the available configuration options and how best to use them.

Environment Variables​

The available environment variables can either accept explicit values or load the target values from a file. Specifying any of the environment variables below with a _FILE suffix will direct the system to take that environment variable value as a path to a file containing the value of interest. This is useful for secrets management systems where you want to keep the values out of the process environment (which might be able to be inspected by individuals with access to docker inspect <container>, for example).

note

Some of the variables descriptions below make use of a # character. In these cases you can specify the same variables multiple times. Replace the # character with a number. 

GATEWAY_NETWORK_0_HOST=1.2.3.4
GATEWAY_NETWORK_0_PORT=8088
GATEWAY_NETWORK_0_DESCRIPTION="For tag server"
 
GATEWAY_NETWORK_1_HOST=5.6.7.8
GATEWAY_NETWORK_1_PORT=8089
GATEWAY_NETWORK_1_DESCRIPTION="For edge server"
VariableRequiresDescription
TZAnySet to a valid TZ database name, like America/Los_Angeles. See List of tzdata Entries for complete selection.
ACCEPT_IGNITION_EULA8.1.7+Set to Y to accept the Ignition EULA automatically (see Licensing section below).
GATEWAY_RESTORE_DISABLED8.1.7+Set to true to have the restored gwbk disabled on startup.
GATEWAY_ADMIN_USERNAME8.1.8+Defaults to admin when not specified, used to set value for initial Gateway auto-commissioning.
GATEWAY_ADMIN_PASSWORD8.1.8+Password value or salted hash to be used for initial Gateway auto-commissioning.
GATEWAY_HTTP_PORT8.1.8+Defaults to 8088 when not specified, used to override the HTTP port used by the Gateway container.
GATEWAY_HTTPS_PORT8.1.8+Defaults to 8043 when not specified, used to override the HTTPS port used by the Gateway container.
GATEWAY_GAN_PORT8.1.8+Defaults to 8060 when not specified, used to override the Gateway Network port used by the Gateway container.
IGNITION_EDITION8.1.8+Set to standard, edge, or maker, used to set value for initial Gateway auto-commissioning.
IGNITION_LICENSE_KEY8.1.8+8-character license key (XXXX-XXXX) for leased activation (e.g. Maker Edition), used to set value for initial Gateway auto-commissioning

New in 8.1.19
You can activate multiple 8-character license keys at the same time in a comma-delimited format, such as: ABCD-1234,DCBA-4321,WXYZ-6789,ZYXW-9876.

Changed in 8.1.20
Changes to this variable will now update the leased activation license configuration after initial commissioning. Previously, they would only be absorbed if an existing leased activation configuration was not present.
IGNITION_ACTIVATION_TOKEN8.1.8+Activation token for the license key.

New in 8.1.19
You can activate multiple 8-character license keys at the same time in a comma-delimited format, such as: abcdef1234...789,bcdef2345...890.

Changed in 8.1.20
Changes to this variable will now update the leased activation license configuration after initial commissioning. Previously, they would only be absorbed if an existing leased activation configuration was not present.
GATEWAY_NETWORK_#_HOST8.1.10+Hostname (or IP) for Outgoing GAN Connection Definition for #.
GATEWAY_NETWORK_#_PORT8.1.10+Port Number to use for connection n (defaults to 8060 when not specified)
GATEWAY_NETWORK_#_PINGRATE8.1.10+Ping Rate (ms) for connection # (defaults to 1000 when not specified)
GATEWAY_NETWORK_#_PINGMAXMISSED8.1.10+Number of missed pings allowed for connection # (defaults to 30 when not specified)
GATEWAY_NETWORK_#_ENABLED8.1.10+Set true or false to mark connection # enabled or disabled
GATEWAY_NETWORK_#_ENABLESSL8.1.10+Set true or false to enable SSL on connection # (defaults to true).
GATEWAY_NETWORK_#_WEBSOCKETTIMEOUT8.1.10+Timeout (ms) for web socket # (defaults to 10000 when not specified)
EAM_SETUP_INSTALLSELECTION8.1.10+Set Agent or Controller to define the EAM target config (defaults to Agent when not specified)
EAM_AGENT_CONTROLLERSERVERNAME8.1.10+Gateway Name (not hostname) of EAM Controller to bind to
EAM_AGENT_SENDSTATSINTERVAL8.1.10+Interval (seconds) to send statistics to the EAM Controller (defaults to 5 when not specified)
EAM_CONTROLLER_ARCHIVEPATH8.1.10+Filesystem path to store EAM Archives (Gateway backups, etc) (defaults to data/eam_archive when not specified)
EAM_CONTROLLER_DATASOURCE8.1.10+The database connection name to use for recording agent history.
EAM_CONTROLLER_ARCHIVELOCATION8.1.10+When set to MANUAL, the path set in EAM_CONTROLLER_ARCHIVEPATH will be used. Defaults to AUTOMATIC, if omitted.
EAM_CONTROLLER_LOWDISKTHRESHOLDMB8.1.10+Value is in megabytes. Errors will be reported in this Gateway when the disk used for archiving drops below this value.
GATEWAY_MODULES_ENABLED8.1.17+A comma-delimited set of identifiers that will whitelist the set of built-in modules that will remain installed prior to Gateway startup. This feature will help with container re-creation events where you want to ensure only a subset of modules remain enabled. See the Module Identifiers table below.
IGNITION_UID8.1.17+Numeric user ID for the target user. Passing this variable and IGNITION_GID allows Ignition to run within a container as an ignition user rather than as the root user. When set, the entrypoint will automatically update file ownerships for the Ignition installation on startup to match the target user prior to stepping down from the root user to launch the Gateway.

Changed in 8.1.26
The default user, as well as default file ownership, has been changed from the root user (UID 0) to a standard ignition user (UID 2003).
If upgrading from a version prior to 8.1.26, you may need to take additional steps to migrate your users. Attempting to launch a container against an old data volume without migrating your users can result in file permission errors. You may also continue running your container as a root user by explicitly setting the UID and GID to 0, but this is discouraged due to security concerns. See the User Migration section
IGNITION_GID8.1.17+Numeric group ID for the target user. Passing this variable and IGNITION_UID allows Ignition to run within a container as an ignition user rather than as the root user. When set, the entrypoint will automatically update file ownerships for the Ignition installation on startup to match the target user prior to stepping down from the root user to launch the Gateway.

Changed in 8.1.26
The default user, as well as default file ownership, has been changed from the root user (GID 0) to a standard ignition user (GID 2003).
If upgrading from a version prior to 8.1.26, you may need to take additional steps to migrate your users. Attempting to launch a container against an old data volume without migrating your users can result in file permission errors. You may also continue running your container as a root user by explicitly setting the UID and GID to 0, but this is discouraged due to security concerns. See the User Migration section on this page for more details.
DISABLE_QUICKSTART8.1.23+Boolean to decide whether or not the "Enable Quick Start" prompt will appear when new Gateway Containers are created. A setting of true will skip the Quick Start prompt.
GATEWAY_NETWORK_#_DESCRIPTION8.1.26+
New in 8.1.26
Documentation about how the connection is used if entered.
GATEWAY_NETWORK_ENABLED8.1.32+Set to false to disable using the Gateway Network.
GATEWAY_NETWORK_REQUIRESSL8.1.32+If true, only connections that use SSL to encrypt traffic will be allowed. This setting only applies to incoming connections.
GATEWAY_NETWORK_REQUIRETWOWAYAUTH8.1.32+Enforces two-way SSL authentication. If true, you will need to install the remote machine's certificate on this machine, in addition to manual approval of this machine's certificate on the remote machine.
GATEWAY_NETWORK_SENDTHREADS8.1.32+The maximum number of threads that will be used to upload messages. Applies to outgoing connections.
GATEWAY_NETWORK_RECEIVETHREADS8.1.32+The maximum number of threads that will be used to download messages. Applies to outgoing connections.
GATEWAY_NETWORK_RECEIVEMAX8.1.32+Number of received messages that can be held until they are processed by the local system. When this capacity is exceeded, new messages are rejected and errors are reported to the remote Gateway. Applies to incoming connections.
GATEWAY_NETWORK_ALLOWINCOMING8.1.32+If false, only outward connections defined on this Gateway will be allowed.
GATEWAY_NETWORK_SECURITYPOLICY8.1.32+Dictates what connections are allowed. If set to ApprovedOnly, incoming connections must be approved from the Incoming Connections page. Other options include Unrestricted and SpecifiedList.
GATEWAY_NETWORK_WHITELIST8.1.32+If connection policy is set to Specified List, this is the comma-separated list of Gateway names which will be allowed to connect.
GATEWAY_NETWORK_ALLOWEDPROXYHOPS8.1.32+The maximum number of proxy hops which could be used to reach the destination Gateway. Any number less than or equal to zero is equivalent to no proxy hops allowed.
GATEWAY_NETWORK_WEBSOCKETSESSIONIDLETIMEOUT8.1.32+The maximum number of milliseconds that a websocket is allowed to remain idle before it is closed. This value should always be set higher than outgoing connection ping rates to avoid premature connection termination.
GATEWAY_ENCODING_KEY8.1.38+The secret key used by the Gateway to encode credentials.
GATEWAY_ENCODING_KEY_FILE8.1.38+The path to a file containing the secret key used to encode credentials.

Module Identifiers Table​

Module IdentifierModule Filename
alarm-notificationAlarm Notification-module.modl
allen-bradley-driversAllen-Bradley Drivers-module.modl
bacnet-driverBACnet Driver-module.modl
dnp3-driverDNP3-Driver.modl
dnp3-driver-v2
New in 8.1.36
DNP3-Driver-v2.modl
enterprise-administrationEnterprise Administration-module.modl
iec-61850-driver
New in 8.1.25
IEC 61850 Driver-module.modl
logix-driverLogix Driver-module.modl
micro800-driver
New in 8.1.39
Micro800 Driver-module.modl
mitsubishi-driverMitsubishi-Driver.modl
modbus-driver-v2Modbus Driver v2-module.modl
omron-driverOmron-Driver.modl
opc-uaOPC-UA-module.modl
perspectivePerspective-module.modl
reportingReporting-module.modl
serial-support-clientSerial Support Client-module.modl
serial-support-gatewaySerial Support Gateway-module.modl
sfcSFC-module.modl
siemens-driversSiemens Drivers-module.modl
sms-notificationSMS Notification-module.modl
sql-bridgeSQL Bridge-module.modl
symbol-factorySymbol Factory-module.modl
tag-historianTag Historian-module.modl
udp-tcp-driversUDP and TCP Drivers-module.modl
visionVision-module.modl
voice-notificationVoice Notification-module.modl
web-browserWeb Browser Module.modl
web-developerWeb Developer Module.modl

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​

OptionRequiresArgumentsDescriptions
-n8.1.0+StringGateway name to be applied to the Ignition Gateway on startup
-a8.1.0+StringPublic web address*
-h8.1.0+IntegerPublic HTTP port*
-s8.1.0+IntegerPublic HTTPS port*
-m8.1.0+IntegerMax memory for JVM
-r8.1.7+StringPath to Gateway Backup for Automated Restore

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

Flags​

FlagRequiresDescription
-d8.1.0+Debug mode, applicable to development - attaches port 8000 for remote JVM debugging. Port 8000 will also likely need to be published on the container.

Supplemental JVM and Wrapper Arguments​

New in 8.1.8

You can also specify JVM and Java Service Wrapper arguments to your Docker containers runtime arguments by adding a double-hyphen to delimit these arguments from the other runtime arguments listed above. Wrapper arguments (starting with wrapper.* ) will be merged and JVM arguments added to those specified in the ignition.conf file.

New in 8.1.38

Two leased licensing parameters are now available to adjust session termination settings. See the example below or the Leased Licensing Parameters section for more information.

Gateway Arguments​

New in 8.1.10

The image also supports the use of Gateway arguments, allowing you to modify the gateway.xml file when launching a container. Like JVM and wrapper arguments, Gateway arguments must be specified after a double-hyphen. Only entries in the file that follow the pattern of "gateway.#" can be modified in this way.

Changed in 8.1.16

Docker image entrypoint will no longer forcibly recreate the gateway.xml file on each launch, allowing for settings adjustments from the Gateway web UI to properly persist without static definition in the container configuration.

Logging Settings​

Unlike the non-containerized version of Ignition, the Ignition container image is designed to emit logs to stdout (“standard out”) so they can be leveraged by various logging drivers in the container engine. This is done by directing what would normally be stored in the logs/wrapper.log file to stdout. As a result, Ignition itself doesn’t control rotating the wrapper.log based on size, which can result in container logs growing unbounded. You can configure the default logging driver to constrain maximum log sizes. Reference the Docker logging configuration page to specify logger size limits.

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
Multiline commands

Note that for Linux/macOS/WSL, you can use the backslash for multi-line commands for better readability. You can substitute the backtick ` for Powershell and caret ^ for Windows Command prompt, these characters technically "escape" the newline character, so make sure they are the last character on a given line.

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​

New in 8.1.12
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​

New in 8.1.8

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
What if I restart the container

The Gateway restore will only apply on a fresh Gateway launch. Subsequent restarts of the container will not restore the indicated Gateway backup.

Automate the Commissioning of a Fresh Gateway​

New in 8.1.8
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
Reading Environment Variables from a file

You can also specify environment variables in the form of <env var>_FILE=/path/to/file in order to have the environment variable value resolved by reading it from a file. This is helpful for secrets management systems within container orchestrators such as Docker Swarm and Kubernetes.

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 \
    -Dignition.license.leased-activation-terminate-sessions-on-shutdown=true \
    -XX:MaxGCPauseMillis=200
New in 8.1.10

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.

Compose Example
# 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:

Integrate Third-Party Modules After an Upgrade​

When upgrading Ignition in Docker, third-party modules are not included with new images, so they will need to be re-installed. You can do this by creating a Docker derived image and use the derived image to copy these modules to the upgraded container. The example below describes how to conduct a derived image build to integrate third-party modules.

For this example, a module subfolder with the modules we are attempting to integrate will be labeled gw-build. The subfolder will also include a Dockerfile. The docker-compose.yml file needed for this process is located outside of this subfolder. We will be using a docker-compose.yml file similar to the previous example, but instead of using an image tag, we will be using a build tag.

docker-compose.yml
services:
  gateway:
    build:
      context: gw-build
      ## Specify the upstream version to derive from for the build argument in the Docker file.
      args:
        IGNITION_VERSION: 8.1.28
    ports:
      - 8088:8088
    volumes:
      - gateway-data:/usr/local/bin/ignition/data
    environment:
      ACCEPT_IGNITION_EULA: "Y"
      GATEWAY_ADMIN_PASSWORD: password
      IGNITION_EDITION: standard
    command: >
      -n Ignition-supp-66195
 
volumes:
  gateway-data:

The Dockerfile within the gw-build folder will define the derived image by containing a build argument for the Ignition version. Notice this does not give a default version. This is because the version we want to build is specified and passed through our docker-compose definition. Next, we will add a command to copy the module files from this folder to the user-lib module folder inside the new Ignition image.

Dockerfile
ARG IGNITION_VERSION
FROM inductiveautomation/ignition:${IGNITION_VERSION}
 
COPY *.modl /usr/local/bin/ignition/user-lib/modules/

With these files defined, we can now run docker compose build to pull the image, perform all derived image build steps, and create the new image.

note

Since docker compose build needs to be run each time a new module is added, you can alternatively add pull_policy: build in the yml file to auto-rebuild each time.

User Migration - Docker Compose​

The following example uses Docker Compose to demonstrate how to migrate the container user and file ownership from the root user to a standard, non-elevated ignition user. If you are instead using the command line, see the next example for migrating users. Your environment may vary, depending on how your container is set up. This container is running Ignition version 8.1.25:

User Migration Example (Docker Compose)
# User Migration Example (Docker Compose)
---
services:
  # Ignition Gateway
  gateway:
    image: inductiveautomation/ignition:8.1.25
    volumes:
      - ignition-data:/usr/local/bin/ignition/data
    ports:
      - 8088:8088
    command: >
      -n docker-test
 
volumes:
  ignition-data:

  1. Upgrade the container to the latest version by changing the image tag to the version you want to upgrade to:

    User Migration Example (Docker Compose)
    # User Migration Example (Docker Compose)
    ---
    services:
      # Ignition Gateway
      gateway:
        image: inductiveautomation/ignition:8.1.26
        volumes:
          - ignition-data:/usr/local/bin/ignition/data
        ports:
          - 8088:8088
        command: >
          -n docker-test

    volumes:
      ignition-data:

  2. Add the IGNITION_UID=2003 and IGNITION_GID=2003 environment variables to update the container permissions:

    User Migration Example (Docker Compose)

    # User Migration Example (Docker Compose)
    ---
    services:
      # Ignition Gateway
      gateway:
        image: inductiveautomation/ignition:8.1.26
        volumes:
          - ignition-data:/usr/local/bin/ignition/data
        ports:
          - 8088:8088
        environment:
          - IGNITION_UID=2003
          - IGNITION_GID=2003
        command: >
          -n docker-test

    volumes:
      ignition-data:

  3. Declare the root user (user: "0:0"):

    User Migration Example (Docker Compose)

    # User Migration Example (Docker Compose)
    ---
    services:
      # Ignition Gateway
      gateway:
        image: inductiveautomation/ignition:8.1.26
        volumes:
          - ignition-data:/usr/local/bin/ignition/data
        ports:
          - 8088:8088
        environment:
          - IGNITION_UID=2003
          - IGNITION_GID=2003
        user: "0:0"
        command: >
          -n docker-test

    volumes:
      ignition-data:

  4. Save the Docker Compose file, then run docker compose up -d.

    note

    By default, we are using the -d option in our Docker command. While you can also run the command without -d, the -d option runs the container in detached mode, allowing the container to run in the background even after closing the terminal.

  5. The container will now use the root user when it starts up, but will launch Ignition as a standard ignition user. All of the files in the ignition-data volume have the proper ownership. We can now remove the IGNITION_UID and IGNITION_GID environment variables and the user:"0:0" override:

    User Migration Example (Docker Compose)
    # User Migration Example (Docker Compose)
    ---
    services:
      # Ignition Gateway
      gateway:
        image: inductiveautomation/ignition:8.1.26
        volumes:
          - ignition-data:/usr/local/bin/ignition/data
        ports:
          - 8088:8088
        command: >
          -n docker-test

    volumes:
      ignition-data:

  6. Finally, we can rerun the docker compose up -d command to recreate the container. Since we removed the environment variables and updated container permissions, the container will launch with the default user being a standard ignition user.

  7. To check if the user successfully migrated over, we see the process listing and who the user is for each process using the command docker compose exec gateway ps aux in the terminal. Additionally, you can use the command docker compose exec gateway whoami to see who the default user for the container is:

User Migration - Command Line​

The following example uses the command line to demonstrate how to migrate the container user and file ownership from the root user to a standard, non-elevated ignition user. If you are instead using Docker Compose, see the preceding example. Your environment may vary, depending on how your container is set up. The following container is called example-gw and is running Ignition version 8.1.25:

User Migration Example (Command Line)
docker run --name example-gw -v example-gw-data:/usr/local/bin/ignition/data \
    -e IGNITION_EDITION=standard -e ACCEPT_IGNITION_EULA=Y -e GATEWAY_ADMIN_PASSWORD=password \
    -p 8088:8088 \
    inductiveautomation/ignition:8.1.25 \
    -n example-gw

  1. Stop and remove your Docker container using the following commands. Keep in mind that you will need to replace example-gw with your container name:

    User Migration Example (Command Line)
    # Stop and remove container
    docker stop example-gw
    docker rm example-gw

  2. Modify the container run configuration to declare the root user using --user 0:0 (The UID and GID will both be 0):

    User Migration Example (Command Line)
    # Declare the root user
    docker run --name example-gw --rm -v example-gw-data:/usr/local/bin/ignition/data \
        -p 8088:8088 \
        --user 0:0 \
        inductiveautomation/ignition:8.1.25 \
        -n example-gw

  3. Update the container permissions by adding the IGNITION_UID and IGNITION_GID environment variables. You can do this by adding -e IGNITION_UID=2003 -e IGNITION_GID=2003 after --user 0:0:

    User Migration Example (Command Line)
    # Update the container permissions
    docker run --name example-gw --rm -v example-gw-data:/usr/local/bin/ignition/data \
        -p 8088:8088 \
        --user 0:0 -e IGNITION_UID=2003 -e IGNITION_GID=2003 \
        inductiveautomation/ignition:8.1.25 \
        -n example-gw

  4. The container's Gateway should now be running under a standard ignition user, using a UID of 2003 and a GID of 2003. You can run the following command to count the number of processes running as a standard ignition user:

    User Migration Example (Command Line)
    # Count the number of running processes under the ignition user
    docker exec example-gw pgrep -u 2003 -c
    note

    There should be 3 processes:

    • the entrypoint
    • the Java wrapper
    • the Java process

  5. File ownership should now also belong to the standard ignition user. You can use the following command to verify that there are no files owned by any other user aside from the standard ignition user:

    User Migration Example (Command Line)
    # Verify file ownership
    docker exec example-gw bash -c "find /usr/local/bin/ignition ! -user 2003 | wc -l"

  6. Once you have verified file ownership and the user the processes are running under, you can now recreate the container against the new image with the default ignition user (UID = 2003) and update your Gateway to the latest version:

    User Migration Example (Command Line)
    # Recreate the container
    docker stop example-gw
    docker rm example-gw
    docker run --name example-gw --rm -v example-gw-data:/usr/local/bin/ignition/data \
        -p 8088:8088 \
        inductiveautomation/ignition:8.1.<new> \
        -n example-gw

Credential Encoding​

You can provide your own non-default encoding key for your Gateway credentials directly on the GATEWAY_ENCODING_KEY environment variable, or specify a file path that leads to a file containing the encoding key using GATEWAY_ENCODING_KEY_FILE. For security purposes, we recommend specifying a file path to a file containing your secret value, especially if you are using your container in a production environment. In this case, you can use file permissions to lock down the file to read only access for the user running the Gateway process.

Keep in mind that changing the encoding key will render your previous secret, encrypted with the old key, unusable. Your secrets will need to be reset after changing the encoding key so that they are encrypted with the new key.

note

Regardless of how you are storing your secret, your secret value needs to be at least 24 bytes. Smaller values will result in a Java security error.

Additionally, we recommend using a random string of printable ASCII characters from the Base64 character set, generated from a secure random number generator. This will help make it clear that each character corresponds with a UTF-8 byte in the key.

Using GATEWAY_ENCODING_KEY_FILE​

The following example uses Docker Compose with secrets to demonstrate how to use the GATEWAY_ENCODING_KEY_FILE variable by specifying a file path:

GATEWAY_ENCODING_KEY_FILE Example
# 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.39
    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
      - GATEWAY_ENCODING_KEY_FILE=/run/secrets/gateway-encoding-key
      - 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/my_password_file.txt
  gateway-encoding-key:
    file: secrets/my_encoding_key_file.txt
 
volumes:
  gw-data:

Using GATEWAY_ENCODING_KEY​

As stated above, you can use the GATEWAY_ENCODING_KEY environment variable to specify a secret, although this is not recommended. However, this method may be useful if you are using the container in a testing environment, but do not want to use the default value. The following example shows how the GATEWAY_ENCODING_KEY variable would be used, with a randomized hexadecimal string:

GATEWAY_ENCODING_KEY Example
environment:
      - ACCEPT_IGNITION_EULA=Y
      - GATEWAY_ADMIN_USERNAME=admin
      - GATEWAY_ADMIN_PASSWORD_FILE=/run/secrets/gateway-admin-password
      - GATEWAY_ENCODING_KEY=44de90db908ac90256a19985d4d77792675ffd1dd8b2ec05
      - IGNITION_EDITION=standard
      - TZ=America/Chicago  # see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List

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.

Last updated on by ia-nboehnke