--- title: Ping Identity DevOps Docker Image - pingdirectory description: This docker image includes the Ping Identity PingDirectory product binaries and associated hook scripts to create and run a PingDirectory instance or instances. component: devops page_id: devops::docker-images/pingdirectory/README canonical_url: https://developer.pingidentity.com/devops/docker-images/pingdirectory/README.html section_ids: devops-ping-identity-devops-docker-image: Ping Identity DevOps Docker Image - pingdirectory devops-related-docker-images: Related Docker Images devops-environment-variables: Environment Variables devops-ports-exposed: Ports Exposed devops-running-a-pingdirectory-container: Running a PingDirectory container devops-running-a-sample-100sec-search-rate-test: Running a sample 100/sec search rate test devops-connecting-with-an-ldap-client: Connecting with an LDAP Client devops-stoppingremoving-the-container: Stopping/Removing the container devops-docker-container-hook-scripts: Docker Container Hook Scripts --- # Ping Identity DevOps Docker Image - `pingdirectory` ## Ping Identity DevOps Docker Image - `pingdirectory` This docker image includes the Ping Identity PingDirectory product binaries and associated hook scripts to create and run a PingDirectory instance or instances. ### Related Docker Images * `pingidentity/pingbase` - Parent Image > This image inherits inherits, and can use, Environment Variables from [pingidentity/pingbase](https://devops.pingidentity.com/docker-images/pingbase/) * `pingidentity/pingdatacommon` - Common Ping files (i.e. hook scripts) ### Environment Variables In addition to environment variables inherited from **[pingidentity/pingbase](https://devops.pingidentity.com/docker-images/pingbase/)**, the following environment `ENV` variables can be used with this image. | ENV Variable | Default | Description | | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | SHIM | ${SHIM} | | | IMAGE\_VERSION | ${IMAGE\_VERSION} | | | IMAGE\_GIT\_REV | ${IMAGE\_GIT\_REV} | | | DATE | ${DATE} | | | PING\_PRODUCT\_VERSION | ${VERSION} | | | PING\_PRODUCT | PingDirectory | Ping product name | | LICENSE\_DIR | ${PD\_LICENSE\_DIR} | PD License directory. This value is set from the pingbase docker file | | LICENSE\_FILE\_NAME | PingDirectory.lic | Name of license File | | LICENSE\_SHORT\_NAME | PD | Short name used when retrieving license from License Server | | LICENSE\_VERSION | ${LICENSE\_VERSION} | Version used when retrieving license from License Server | | REPLICATION\_PORT | 8989 | Default PingDirectory Replication Port | | ADMIN\_USER\_NAME | admin | Replication administrative user | | STARTUP\_COMMAND | ${SERVER\_ROOT\_DIR}/bin/start-server | The command that the entrypoint will execute in the foreground to instantiate the container | | PD\_DELEGATOR\_PUBLIC\_HOSTNAME | localhost | Public hostname of the DA app | | STARTUP\_FOREGROUND\_OPTS | --nodetach | The command-line options to provide to the the startup command when the container starts with the server in the foreground. This is the normal start flow for the container | | STARTUP\_BACKGROUND\_OPTS | | The command-line options to provide to the the startup command when the container starts with the server in the background. This is the debug start flow for the container | | ROOT\_USER\_PASSWORD\_FILE | | Location of file with the root user password (i.e. cn=directory manager). Defaults to /SECRETS\_DIR/root-user-password | | ADMIN\_USER\_PASSWORD\_FILE | | Location of file with the admin password, used as the password replication admin Defaults to /SECRETS\_DIR/admin-user-password | | ENCRYPTION\_PASSWORD\_FILE | | Location of file with the passphrase for setting up encryption Defaults to /SECRETS\_DIR/encryption-password | | KEYSTORE\_FILE | | Location of the keystore file containing the server certificate. If left undefined, the SECRETS\_DIR will be checked for a keystore. If that keystore does not exist, the server will generate a self-signed certificate. | | KEYSTORE\_PIN\_FILE | | Location of the pin file for the keystore defined in KEYSTORE\_FILE. You must specify a KEYSTORE\_PIN\_FILE when a KEYSTORE\_FILE is present. This value does not need to be defined when allowing the server to generate a self-signed certificate. | | KEYSTORE\_TYPE | | Format of the keystore defined in KEYSTORE\_FILE. One of "jks", "pkcs12", "pem", or "bcfks" (in FIPS mode). If not defined, the keystore format will be inferred based on the file extension of the KEYSTORE\_FILE, defaulting to "jks". | | TRUSTSTORE\_FILE | | Location of the truststore file for the server. If left undefined, the SECRETS\_DIR will be checked for a truststore. If that truststore does not exist, the server will generate a truststore, containing its own certificate. | | TRUSTSTORE\_PIN\_FILE | | Location of the pin file for the truststore defined in TRUSTSTORE\_FILE. You must specify a TRUSTSTORE\_PIN\_FILE when a TRUSTSTORE\_FILE is present. This value does not need to be defined when allowing the server to generate a truststore. | | TRUSTSTORE\_TYPE | | Format of the truststore defined in TRUSTSTORE\_FILE. One of "jks", "pkcs12", "pem", or "bcfks" (in FIPS mode). If not defined, the truststore format will be inferred based on the file extension of the TRUSTSTORE\_FILE, defaulting to "jks". | | TAIL\_LOG\_FILES | ${SERVER\_ROOT\_DIR}/logs/access ${SERVER\_ROOT\_DIR}/logs/errors ${SERVER\_ROOT\_DIR}/logs/failed-ops ${SERVER\_ROOT\_DIR}/logs/config-audit.log ${SERVER\_ROOT\_DIR}/logs/debug-trace ${SERVER\_ROOT\_DIR}/logs/debug-aci ${SERVER\_ROOT\_DIR}/logs/tools/.log ${SERVER\_BITS\_DIR}/logs/tools/.log | Files tailed once container has started | | MAKELDIF\_USERS | 0 | Number of users to auto-populate using make-ldif templates | | RETRY\_TIMEOUT\_SECONDS | 180 | The default retry timeout in seconds for dsreplication and remove-defunct-server | | PD\_PROFILE | ${STAGING\_DIR}/pd.profile | Directory for the profile used by the PingData manage-profile tool | | FIPS\_MODE\_ON | false | Turns on FIPS mode (currently with the Bouncy Castle FIPS provider) set to exactly "true" lowercase to turn on set to anything else to turn off | | FIPS\_PROVIDER | BCFIPS | BCFIPS is the only provider currently supported — do not edit | | PD\_REBUILD\_ON\_RESTART | false | Force a rebuild (replace-profile) of a PingDirectory on restart. Used to ensure that the server configuration exactly matches the server profile. This variable will slow down startup times and should only be used when necessary. | | UNBOUNDID\_SKIP\_START\_PRECHECK\_NODETACH | true | Setting this variable to true speeds up server startup time by skipping an unnecessary JVM check. | | REPLICATION\_BASE\_DNS | | Base DNs to include when enabling replication, in addition to the always-included USER\_BASE\_DN. Multiple base DNs can be specified here, separated by a `;` character | | RESTRICTED\_BASE\_DNS | | Base DNs to set as --restricted when enabling replication. Multiple base DNs can be specified here, separated by a `;` character. See the product documentation for more information on how to configure entry balancing. | | PARALLEL\_POD\_MANAGEMENT\_POLICY | false | Whether this container is running as a Pod in a Kubernetes StatefulSet, and that StatefulSet is using the Parallel podManagementPolicy. This property allows for starting up Pods in parallel to speed up the initial startup of PingDirectory topologies. This variable must be set to true when using the Parallel podManagementPolicy. Note: when using parallel startup, ensure the RETRY\_TIMEOUT\_SECONDS variable is large enough. The pods will be enabling replication simultaneously, so some pods will have to retry while waiting for others to complete. If the timeout is too low, a Pod may end up restarting unnecessarily. | | SKIP\_WAIT\_FOR\_DNS | false | Set to true to skip the waiting for DNS step that is normally done just before attempting to join the topology. | | CERTIFICATE\_NICKNAME | | There is an additional certificate-based variable used to identity the certificate alias used within the `KEYSTORE_FILE`. That variable is called `CERTIFICATE_NICKNAME`, which identifies the certificate to use by the server in the `KEYSTORE_FILE`. If a value is not provided, the container will look at the list certs found in the `KEYSTORE_FILE` and if one - and only one - certificate is found of type `PrivateKeyEntry`, that alias will be used. | | PD\_FORCE\_DATA\_REIMPORT | false | Set to true to force PingDirectory to export and re-import its backend data on restart. Note that this process can take a long time for large backends. | | LOAD\_BALANCING\_ALGORITHM\_NAMES | | The load-balancing algorithm names to set for this server instance. This variable is only needed when enabling automatic server discovery with PingDirectoryProxy. Multiple algorithms can be specified here, separated by a `;` character | | FAIL\_ON\_DISABLED\_BASE\_DN | false | Set to true to fail the container if it is found that replication is not enabled for the USER\_BASE\_DN during startup. If replication is not enabled for the DN but this variable is not set to true, then a warning will be printed, but the container will not fail. | | FAIL\_ON\_UNSUCCESSFUL\_REMOVE\_DEFUNCT | false | Set to true to fail the container if it is found that a previous call to remove-defunct-server in the hook scripts failed. If there was a failure but this variable is not set to true, then a warning will be printed, but the container will not fail. Failure of remove-defunct-server is marked by a file at ${SERVER\_ROOT\_DIR}/logs/remove-defunct-server-marker. Logs for the tool can be found at ${SERVER\_ROOT\_DIR}/logs/tools/remove-defunct-server.log | | COLUMNS | 120 | Sets the number of columns in PingDirectory command-line tool output | ### Ports Exposed The following ports are exposed from the container. If a variable is used, then it may come from a parent container * ${LDAP\_PORT} * ${LDAPS\_PORT} * ${HTTPS\_PORT} * ${JMX\_PORT} ### Running a PingDirectory container The easiest way to test a simple standalone image of PingDirectory is to cut/paste the following command into a terminal on a machine with docker. ```shell docker run \ --name pingdirectory \ --publish 1389:1389 \ --publish 8443:1443 \ --detach \ --env SERVER_PROFILE_URL=https://github.com/pingidentity/pingidentity-server-profiles.git \ --env SERVER_PROFILE_PATH=getting-started/pingdirectory \ --env PING_IDENTITY_ACCEPT_EULA=YES \ --env PING_IDENTITY_DEVOPS_USER \ --env PING_IDENTITY_DEVOPS_KEY \ --tmpfs /run/secrets \ pingidentity/pingdirectory:edge ``` You can view the Docker logs with the command: ```shell docker logs -f pingdirectory ``` You should see the ouptut from a PingDirectory install and configuration, ending with a message the the PingDirectory has started. After it starts, you will see some typical access logs. Simply `Ctrl-C` after to stop tailing the logs. ### Running a sample 100/sec search rate test With the PingDirectory running from the previous section, you can run a `searchrate` job that will send load to the directory at a rate if 100/sec using the following command. ```shell docker exec -it pingdirectory \ /opt/out/instance/bin/searchrate \ -b dc=example,dc=com \ --scope sub \ --filter "(uid=user.[1-9])" \ --attribute mail \ --numThreads 2 \ --ratePerSecond 100 ``` ### Connecting with an LDAP Client Connect an LDAP Client (such as Apache Directory Studio) to this container using the default ports and credentials | | | | ------------- | ----------------- | | LDAP Port | 1389 | | LDAP Base DN | dc=example,dc=com | | Root Username | cn=administrator | | Root Password | 2FederateM0re | ### Stopping/Removing the container To stop the container: ```shell docker container stop pingdirectory ``` To remove the container: ```shell docker container rm -f pingdirectory ``` ### Docker Container Hook Scripts Please go [here](https://github.com/pingidentity/pingidentity-devops-getting-started/tree/master/docs/docker-images/pingdirectory/hooks/README.md) for details on all pingdirectory hook scripts *** This document is auto-generated from *[pingdirectory/Dockerfile](https://github.com/pingidentity/pingidentity-docker-builds/blob/master/pingdirectory/Dockerfile)* Copyright © 2026 Ping Identity Corporation