Docker Gateway Restore with Compose

[kgamble]

I am trying to setup a gateway to automatically restore from a backup in startup, following the documentation, and there is a command line argument mentioned (-r) that I am unable to find in even Dockers documentation!

Does anyone potentially know what that argument is? So that I can use it in a docker-compose file, because without it the restore doesn’t seem to happen. It says “runtime argument”, but I am not sure if its the same thing as --runtime or just a poor wording coincidence.

Documentation Section

Automating the Restore of a Gateway Backup
The following feature is new in Ignition version 8.1.7
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 Licensingsection 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

[kcollins1]

Everything after the image reference in a docker run is sent to the container as command-line arguments. So it is our entrypoint script that is consuming arguments such as -r /path/to/gateway.gwbk.

[kgamble]

Ahhh, that makes sense.

Then my new question becomes, how can I pass that command line argument to the entrypoint in a compose?

Here is my current yaml:

version: "3"

services:  
  example_gateway:
    image:  inductiveautomation/ignition
    ports:
    - "8088"
    env_file:
    - 'variables.env'
    volumes:
    - ./ignition_gateway.gwbk:/restore.gwbk

As of right now it doesn’t seem to be doing the restore

[kcollins1]

Use the following format:

services:
  gateway:
    ...
    command: >
      -n Ignition-gateway-name
      -r /path/to/restore.gwk

The above makes use of YAML Block Styles, the above condenses to -n ... -r ... all on one line, but offers the convenience of multi-line representation in the YAML file for easy viewing/editing.

EDIT: This example ​in our documentation also shows this technique, combined with the supplying of JVM/Wrapper/Gateway args after the double-hyphen

[kgamble]

So does the /path/to/restore.gwbk need to be defined in the volumes and in the command argument? And is Gateway name required?

(It may be useful to try and explain this a little more in the doc page, its not entirely clear from a user perspective that the -r argument is a command and not like the other tags. Potentially just adding it into the example you mentioned may help?)

EDIT: I shortly realized that the /path/to/restore.gwbk is the path once INSIDE the container, not the path outside the container. So I definitely see why it should be defined both times.

[kcollins1]

@kgamble

So does the /path/to/restore.gwbk need to be defined in the volumes and in the command argument? And is Gateway name required?

The path that you point to with the -r <path to gwbk file> runtime argument does need to exist within the container filesystem. This might be something you bind-mount in via a volume declaration, or it might be something you bake in via a derived image of your own.

I think that the section on runtime arguments in the docs does mention where these options/flags should be supplied. All of those are optional.

[kgamble]

@kcollins1

I think that the section on runtime arguments in the docs does mention where these options/flags should be supplied. All of those are optional.

You are definitely right, I just didn't tie those two sections together in my brain!

As always, I appreciate the clarification Kevin.

For completeness sake, here is the above mentioned compose with the updated content:

version: "3"

services:
  example_gateway:
    image:  inductiveautomation/ignition:latest
    ports:
    - "8088"
    env_file:
    - 'variables.env'
    volumes:
    - ./ignition_client_gateway.gwbk:/restore.gwbk
    command: >
      -n example_gateway_name
      -r /restore.gwbk

[kcollins1]

You’re welcome! Don’t forget to use explicit image tags in your image: declarations! While we provide latest tags, I definitely don’t recommend their use in most cases, as it rarely guarantees that you’re using the latest, rather that you’re only using the last latest that you pulled.

[Ifeoluwashola_Adaral]

I love the explanation you gave here, but one thing that's not really clear to me is the other volume mounted to the container: - ./ignition_client_gateway.gwbk:/restore.gwbk is it the path to where the ignition volume is stored or I'll first run backup, store it in a file and use the file path as the /restore.gwbk

I don't know maybe you understand me

[kgamble]

If you would like to restore a backup on initial creation, than it’s the path to that backup on the docker host

The /restore.gwbk is just the name we picked and gave the -r argument

[Ifeoluwashola_Adaral]

Then is this correct?

services:
 ignition:
   image: inductiveautomation/ignition:latest
   ports:
     - 9088:8088
     - 9060:8060
   volumes:
     - gw-data:/usr/local/bin/ignition/data
     - /var/lib/docker/volumes/ignition_gw-data/_data:/restore.gwbk
   environment:
     - ACCEPT_IGNITION_EULA=Y
     - IGNITION_NETWORK_INTERFACE=docker
     - IGNITION_GATEWAY_ADDRESS=localhost
     - IGNITION_GATEWAY_PORT=9088
     - IGNITION_GATEWAY_SECURE_PORT=9043
   command: >
     - n ignition_gateway
     - r /restore.gwbk

[kcollins1]

@Ifeoluwashola_Adaral

- /var/lib/docker/volumes/ignition_gw-data/_data:/restore.gwbk

No, this is incorrect. The left side of the volume configuration should contain an absolute or relative path to a gateway backup file on the host. The right side (after the :) is then where you want to bind-mount that inside the container.

You might find some inspiration from these examples that I've created as well: GitHub - thirdgen88/ignition-examples: Ignition Examples with Docker Compose.

[Ifeoluwashola_Adaral]

Thank you, I've seen the examples, but I still don't seem to understand it fully, the .gwbk file, does it get created automatically or I'm missing the step of creating it. I think my issue now is how to get the base.gwbk file or anything I want to call the name.

[Ifeoluwashola_Adaral]

Do I have to first manually download the backup from the gateway webpage?

[kcollins1]

Ahhh, yes, those examples reference an already-existing GWBK that you're mounting into the container to restore on the first launch. You don't need that if you're just wanting to start up an Ignition container in its default initial state.

[Ifeoluwashola_Adaral]

Now, I have a gateway which I deployed using compose file, I have some projects on the gateway and I want to restore all my project on another gateway, can I achieve this without having to manually download the backup file on the webpage? Just curious.
And one more thing is how to manage the license key during the process. Thank you

[kcollins1]

@Ifeoluwashola_Adaral

Now, I have a gateway which I deployed using compose file, I have some projects on the gateway and I want to restore all my project on another gateway, can I achieve this without having to manually download the backup file on the webpage?

You can bind-mount a path from your host into the container and target that container path in a Scheduled Backups configuration.

@Ifeoluwashola_Adaral

And one more thing is how to manage the license key during the process.

The gateway backup file will not contain any information about licensing. If you're using containers, you should probably be using Leased Activation licensing with an 8-digit license key.

[Ifeoluwashola_Adaral]

Let's say I bind-mount this path:
volumes: - type: bind source: ./static target: /opt/app/static volumes: myapp:

Then in my scheduled backup I'll target /opt/app/static as my backup folder, right?

[Ifeoluwashola_Adaral]

Look at what I have now

version: '3.7'
services:
 ignition:
   image: inductiveautomation/ignition:latest
   ports:
     - 9088:8088
     - 9060:8060
   volumes:
     - gw-data:/usr/local/bin/ignition/data
     - C:\Users\USER\Downloads\Ignition-d967586f6d3a_Ignition-backup-20240118-0900.gwbk:/restore.gwbk
   environment:
     - ACCEPT_IGNITION_EULA=Y
     - IGNITION_NETWORK_INTERFACE=docker
     - IGNITION_GATEWAY_ADDRESS=localhost
     - IGNITION_GATEWAY_PORT=9088
     - IGNITION_GATEWAY_SECURE_PORT=9043
     - IGNITION_EDITION=standard
     - GATEWAY_ADMIN_USERNAME=admin
     - GATEWAY_ADMIN_PASSWORD=password1
   command: >
     -n ignition_gateway
     -h 9088
     -s 9043
     -a localhost
     -r /restore.gwbk
   logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
   restart: always
volumes: 
  gw-data:

I downloaded the backup file and mount the path to the container and used the runtime -r flag

[Ifeoluwashola_Adaral]

Just in case you can also assist with this. I set scheduled backup but I'm getting permission denied error.