---
title: Manage configuration with Docker
description: Build a base Docker image for PingIDM using the provided Custom.Dockerfile to support file-based configuration in containerized deployments
component: pingidm
version: 8
page_id: pingidm:install-guide:docker
canonical_url: https://docs.pingidentity.com/pingidm/8.1/install-guide/docker.html
llms_txt: https://docs.pingidentity.com/pingidm/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
keywords: ["Installation", "Cluster", "Configuration", "Docker"]
superseded_by: https://docs.pingidentity.com/pingidm/8.1/install-guide/docker.html
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-17` base image:

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

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

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

       => [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-17                                            0.0s
      ```

2. Build the base image for IDM:

   1. Download the latest version of the IDM `.zip` file from the [Backstage](https://backstage.pingidentity.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-17:latest
      ```

      to:

      ```
      FROM my-repo/java-17
      ```

   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.0.3

       => [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.0.3                                                    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.0.3    0cc1b7f70ce6    1 hour ago     387MB
   my-repo/java-17              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.