---
title: Building and running a PingGateway Docker image
description: A Dockerfile is delivered inside PingGateway-2026.3.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 Adding PingGateway configuration to a Docker image.
component: pinggateway
version: 2026
page_id: pinggateway:devops-guide:docker-basic
canonical_url: https://docs.pingidentity.com/pinggateway/2026/devops-guide/docker-basic.html
revdate: 2025-04-01T17:53:34Z
keywords: ["Deployment", "Configuration", "Devops", "Docker"]
section_ids:
  docker-build-image: Build the base image for PingGateway
  docker-run-image: Run the Docker image
  docker-stop-image: Stop the Docker image
  docker-run-image-options: Run options
---

# Building and running a PingGateway Docker image

A Dockerfile is delivered inside `PingGateway-2026.3.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 [Adding PingGateway configuration to a Docker image](docker-add-conf.html).

|   |                                                                                                                                                                                                               |
| - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|   | Ping Identity provides no commercial support for production deployments that use the evaluation-only Docker images. When deploying, you must build and use your own Docker images for production deployments. |

The Docker image has the following characteristics:

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

* PingGateway binaries are installed in `/opt/gateway`. Use the `$INSTALL_DIR` environment variable in your Dockerfiles instead of the directory path.

* PingGateway configuration files are stored in `/var/gateway`. Use the `$IG_INSTANCE_DIR` environment variable in your Dockerfiles instead of the directory path.

* A 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-2026.3.0.zip` from the [Ping Identity Download Center](https://product-downloads.pingidentity.com/), and unzip. The directory `/path/to/ping-gateway-2026.3.0` is created.

2. Go to `/path/to/ping-gateway-2026.3.0`.

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

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

   Output

   ```
   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:

   ```console
   $ docker image list
   ```

   Output

   ```
   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:

   ```console
   $ 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:

   ```console
   $ docker container ls
   ```

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

   ```console
   $ 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:

  ```console
  $ 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`:

  ```console
  $ docker run -p 8090:8080 ig-image
  ```

* `-v configuration directory`

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

  ```console
  $ docker run -v $HOME/.openig:/var/gateway/ ig-image
  ```

* `-user user`

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

  ```console
  $ docker run --user 11111 ig-image
  ```

* `it`

  Run the image in interactive mode:

  ```console
  $ docker run -it ig-image
  ```

* `sh`

  Run the image in sh shell:

  ```console
  $ docker run ig-image sh
  ```