---
title: Manage configuration with Docker
description: Docker is a set of products that allows you to run IDM instances in containers. A container is a software package that can be virtualized. Containerization is one way to use a file-based configuration strategy to manage IDM clusters in a repeatable and reliable way.
component: pingidm
version: 8.1
page_id: pingidm:install-guide:docker
canonical_url: https://docs.pingidentity.com/pingidm/8.1/install-guide/docker.html
keywords: ["Installation", "Cluster", "Configuration", "Docker"]
section_ids:
  build_a_base_image: Build a base image
---

# Manage configuration with Docker

Docker is a set of products that allows you to run IDM instances in *containers*. A container is a software package that can be virtualized. Containerization is one way to use a [file-based configuration](cluster-config-changes.html#file-based-config) strategy to manage IDM clusters in a repeatable and reliable way.

You can download Docker from [the official Docker homepage](https://www.docker.com).

## Build a base image

After you have downloaded and installed Docker, you must build a *base image* for IDM. Ping supplies a `Custom.Dockerfile`, which contains our expected structure. To build a base image with it, do the following:

1. As a prerequisite, you must build the `java-21` base image:

   1. Clone the `https://github.com/ForgeRock/forgeops-extras.git` repository.

   2. Build the `java-21` base image from the `forgeops-extras/images/java-21` directory:

      ```
      cd /path/to/forgeops-extras/images/java-21
      docker build --tag my-repo/java-21 .

       => [internal] load build definition from Dockerfile       0.0s
       => => transferring dockerfile: 2.38kB                     0.0s
       ...
       => => writing image sha256:7674...f7f5                    0.0s
       => => naming to docker.io/my-repo/java-21                 0.0s
      ```

2. Build the base image for IDM:

   1. Download the latest version of the IDM `.zip` file from the [Backstage](https://backstage.forgerock.com/downloads) download site.

   2. Unzip the IDM `.zip` file.

   3. Edit the `Custom.Dockerfile` in the `openidm/bin` directory. Change the line:

      ```
      FROM gcr.io/forgerock-io/java-21:latest
      ```

      to:

      ```
      FROM my-repo/java-21
      ```

   4. Build the `IDM` base image from the `openidm/bin` directory:

      ```
      cd /path/to/openidm/bin
      docker build . --file Custom.Dockerfile --tag my-repo/idm:8.1.0

       => [internal] load build definition from Custom.Dockerfile       0.0s
       => => transferring dockerfile: 648B                              0.0s
       ...
       => => writing image sha256:9550...5788                           0.0s
       => => naming to docker.io/my-repo/idm:8.1.0                      0.0s
      ```

3. Run the `docker images` command to verify that you built the base images:

   ```
   docker images | grep my-repo

   REPOSITORY                   TAG      IMAGE ID        CREATED        SIZE
   my-repo/idm                  8.1.0    0cc1b7f70ce6    1 hour ago     387MB
   my-repo/java-21              latest   76742b285ddf    1 hour ago     146MB
   ```

   |   |                                                                                                                                                                  |
   | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   |   | If you use IDM as part of a platform deployment, refer to [Base Docker images](https://docs.pingidentity.com/forgeops/2025.1/reference/base-docker-images.html). |

After you build your base images, you can push them to your Docker repository. Refer to your registry provider documentation for detailed instructions.