PingGateway 2024.9

Add configuration to a Docker image

The following sections describe how to add configuration to your Docker image. Before working through this section, complete the procedures in Build and run a Docker image.

Run an image with a mutable configuration

This section describes how to add a basic route to your local PingGateway configuration folder, and mount the configuration to the Docker container.

If you change your configuration in a way that doesn’t require PingGateway to restart, you see the change in your running Docker image without restarting it or rebuilding it. For information changes that require restart, refer to When to restart PingGateway after changing the configuration.

Use this procedure to manage configuration externally to the Docker image. For example, use it when developing routes.

  1. Add the following route to your local PingGateway configuration as $HOME/.openig/config/routes/hello.json:

    {
  "name": "hello",
  "handler": {
    "type": "StaticResponseHandler",
    "config": {
      "status": 200,
      "headers": {
        "Content-Type": [ "text/plain; charset=UTF-8" ]
      },
      "entity": "Hello world!"
    }
  },
  "condition": "${find(request.uri.path, '^/hello')}"
}

    The configuration contains a static response handler to return a "Hello world!" statement when the URI of a request finishes with /hello.

  2. Run the Docker image, using the option to mount the local PingGateway configuration directory:

    $ docker run -p 8080:8080 -v $HOME/.openig:/var/ig/ ig-image

  3. Go to http://localhost:8080/hello to access the route in the mounted configuration.

    The "Hello world!" statement is displayed.

  4. Edit hello.json to change the "Hello world!" statement, and save the file.

    Go again to http://localhost:8080/hello to see that the message changed without changing your Docker image.

Run an image with an immutable configuration

This section describes how to add a basic route to your local PingGateway configuration folder, copy it into a new Docker image, and run that Docker image.

Unlike the previous example, the Docker image is immutable. If you change your configuration locally, the Docker image is not changed.

Use this procedure to manage configuration within the Docker image. For example, use it when you want to deploy the same configuration multiple times.

  1. Add the following route to your local PingGateway configuration as $HOME/.openig/config/routes/hello.json:

    {
  "name": "hello",
  "handler": {
    "type": "StaticResponseHandler",
    "config": {
      "status": 200,
      "headers": {
        "Content-Type": [ "text/plain; charset=UTF-8" ]
      },
      "entity": "Hello world!"
    }
  },
  "condition": "${find(request.uri.path, '^/hello')}"
}

    The configuration contains a static response handler to return a "Hello world!" statement when the URI of a request finishes with /hello.

  2. Add the following file to your local PingGateway configuration as $HOME/.openig/Dockerfile, where $HOME/.openig is the instance directory:

    FROM ig-image
COPY config/routes/hello.json "$IG_INSTANCE_DIR"/config/routes/hello.json

    The Dockerfile copies hello.json into the Docker image. The $IG_INSTANCE_DIR environment variable is defined in the PingGateway base image.

  3. Build the Docker image:

    $ docker build . -t ig-custom

Sending build context to Docker daemon
 Step 1/2 : FROM ig-image
 Step 2/2 : COPY config/routes/hello.json "$IG_INSTANCE_DIR"/config/routes/hello.json
 Successfully tagged ig-custom:latest

  4. Make sure the Docker image is available:

    $ docker image list

REPOSITORY               TAG                IMAGE ID
ig-custom                image_tag          51b...3b7
gcr.io/forgerock-io/ig   image_tag          404...a2b

  5. Run the Docker image on port 8080:

    $ docker run -p 8080:8080 ig-custom

  6. Go to http://localhost:8080/hello. The "Hello world!" statement is displayed.