Skip to content

Building a Docker product image locally

This page describes the process to build a Docker image of our products with the build tools found in our Docker Builds repository and a local copy of a product .zip archive.

Video demonstration

For a video demonstration of this process, visit this link.

Cloning a build repository

Open a terminal and clone the pingidentity-docker-builds repo:

git clone

Download a product .zip archive

  1. Go to Product Downloads and download the product to be used to build a Docker image.

    Zip file versus installer

    Ensure you download the product distribution .zip archive and not the Windows installer

  2. When the download has finished, rename the file to

  3. Move to the Build Directory.

    In the pingidentity-docker-builds repository directory for each product, move the file to the <product>/tmp directory, where /<product> is the name of one of our available products. For example:

    mv ~/Downloads/ \

Build the Docker image

Before building the image, display the versions.json file in the product directory. You must specify a valid version for the build script. Since the product .zip archive is being provided, it does not matter which version you select as long as it is valid. For example, you can see that 11.0.3 is a valid product version for PingFederate.

    "latest": "11.0.3",
    "versions": [
            "version": "11.0.3",
            "preferredShim": "alpine:3.15.4",
            "shims": [
                    "shim": "alpine:3.15.4",
                    "preferredJVM": "al11",
                    "jvms": [
                            "jvm": "al11",
                            "build": true,
                            "deploy": true,
                            "registries": [
  1. Go to the base of the pingidentity-docker-builds repo. For example:

    cd ~/pingidentity/devops/pingidentity-docker-builds
  2. Run the script with the appropriate options. For example:

    ./ci_scripts/ \
        -p pingfederate \
        -v 11.0.3 \
        -s alpine:3.15.4 \
        -j al11

    When the build is completed, the product and base images are displayed. For example:

    REPOSITORY                     TAG                                                       IMAGE ID       CREATED              SIZE
    pingidentity/pingfederate      11.0.3-fsoverride-alpine_3.15.4-al11-master-f1ba-x86_64   404a2b14df0c   7 seconds ago        759MB
    pingidentity/pingbase          master-f1ba-x86_64                                        eb7648692b55   About a minute ago   0B
    pingidentity/pingjvm           al11-alpine_3.15.4-master-f1ba-x86_64                     af0e87d8fafd   About a minute ago   108MB
    pingidentity/pingcommon        master-f1ba-x86_64                                        2e82b239e9bb   About a minute ago   997kB
    pingidentity/pingdatacommon    master-f1ba-x86_64                                        13f35b12a918   About a minute ago   1.11MB

    Our Docker images are built using common foundational layers required by the product layer such as the Java virtual machine (JVM), pingcommon, and pingdatacommon.

    As it is unlikely you will have the foundational layers on your local system, build the first time using the script. This script will create the foundational images, and if you want to use the same foundational layers for other builds, you need only run the script to build the product layer.

    You must specify the appropriate options when you run For PingFederate, the options might look like this:

    • -p (Product): pingfederate
    • -v (Version): 11.0.3
      • Note: this is the version retrieved from the versions.json file
    • -s (Shim): alpine
    • -j (Java): al11

Run from the repository root

It is important to build from the base of the repository as shown in the example.

Re-tagging the local image

To change the tag of the created image and push it to your own Docker registry, use the docker tag command:

docker tag [image id] \
   [Docker Registry]/[Organization]/[Image Name]:[tag]

For example:

docker tag 404a2b14df0c \

# Display new tag
docker image ls

# Output snippet
pingidentity/pingfederate            11.0.3-fsoverride-alpine_3.15.4-al11-master-f1ba-x86_64   404a2b14df0c   4 minutes ago   759MB     localbuild                                                404a2b14df0c   4 minutes ago   759MB