PingGateway 2024.9

Build and run a Docker image

A Dockerfile is delivered inside PingGateway-2024.9.0.zip to help you build an evaluation-only, base Docker image for PingGateway. After building and running the Docker image, add a configuration as described in Add configuration to a Docker image.

ForgeRock provides no commercial support for production deployments that use ForgeRock’s evaluation-only Docker images. When deploying the ForgeRock Identity Platform using Docker images, you must build and use your own images for production deployments.

The Docker image has the following characteristics:

  • The Docker image runs on Linux and Mac operating systems.

  • PingGateway binaries are delivered in /opt/ig.

  • The environment variable $IG_INSTANCE_DIR has the value /var/ig.

  • A ForgeRock user with username: forgerock and uid: 11111, runs the PingGateway process and owns the configuration files.

Build the base image for PingGateway

  1. Download PingGateway-2024.9.0.zip from the BackStage download site, and unzip. The directory /path/to/identity-gateway-2024.9.0 is created.

  2. Go to /path/to/identity-gateway-2024.9.0.

  3. With a Docker daemon running, build a base Docker image:

    $ docker build . -f docker/Dockerfile -t ig-image

Sending build context to Docker daemon
Step 1/7 : FROM gcr.io/forgerock-io/...:latest
latest: Pulling from forgerock-io/...
...
Successfully tagged ig-image:latest

  4. Make sure the Docker image is available:

    $ docker image list

REPOSITORY                   TAG        IMAGE ID
ig-image                     latest
gcr.io/forgerock-io/...  latest

Run the Docker image

The following steps run the Docker image on port 8080. Make sure the port is not being used, or use a different port as described in the procedure.

  1. With a Docker daemon running, run the Docker image:

    $ docker run -p 8080:8080 ig-image

    PingGateway starts up, and the console displays the message log.

  2. Go to http://localhost:8080 to view the PingGateway welcome page.

Stop the Docker image

  1. List the Docker containers that are running:

    $ docker container ls

  2. For a container with the status Up, use the container ID to stop the container:

    $ docker container stop CONTAINER_ID

Run options

Consider using the following options when you run the Docker image:

-e IG_OPTS=-Dig.pid.file.mode=value ig-image

Allow startup if there is an existing PID file. PingGateway removes the existing PID file and creates a new one during startup. The following example passes an environment variable with the value override as a Java runtime option:

$ docker run -e "IG_OPTS=-Dig.pid.file.mode=override" ig-image

To prevent restart if there is an existing PID file, set the value to the default fail.

-p port:port

The default ports 8080:8080 equate to local-machine-port:internal-container-port. PingGateway can run on a different port, but the container must always run on 8080. The following example runs PingGateway on port 8090:

$ docker run -p 8090:8080 ig-image
-v configuration directory

The default configuration directory is /var/ig/. The following example sets the configuration directory to $HOME/.openig:

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

Run the image as the provided user. The following example uses the ID 11111:

$ docker run --user 11111 ig-image
it

Run the image in interactive mode:

$ docker run -it ig-image
sh

Run the image in sh shell:

$ docker run ig-image sh