Customizing Server Profiles ¶
When you deployed the full stack of product containers in Getting Started, you were employing the server profiles associated with each of our products. In the YAML files, you'll see entries such as this for each product instance:
environment: - SERVER_PROFILE_URL=https://github.com/pingidentity/pingidentity-server-profiles.git - SERVER_PROFILE_PATH=baseline/pingaccess
Our pingidentity-server-profiles repository indicated by the
SERVER_PROFILE_URL environment variable, contains the server profiles we use for our DevOps deployment examples. The
SERVER_PROFILE_PATH environment variable indicates the location of the product profile data to use. In the example above, the PingAccess profile data is located in the
We use environment variables for certain startup and runtime configuration settings of both standalone and orchestrated deployments. There are environment variables that are common to all product images. You'll find these in the PingBase Image Directory. There are also product-specific environment variables. You'll find these in the Docker Image Reference for each available product.
- You've already been through Get Started to set up your DevOps environment and run a test deployment of the products.
- You understand the Anatomy of the Product Containers.
What You'll Do ¶
Add or change the environment variables used for any of our server profiles to better fit your purposes. These environment variables are located in the Server Profiles Repository for each product.
For example, the location for the env_vars file for PingAccess is located in the baseline/pingaccess server profile.
Modify one of our server profiles to reflect an existing Ping Identity product installation in your organization. You can do this by forking our server profiles repository (
https://github.com/pingidentity/pingidentity-server-profiles) to your Github repository, or by using local directories.
Add or Change Environment Variables ¶
Select any environment variables to add from either the Docker Images in the Docker Images Reference for the product-specific environment variables, or the PingBase Image Directory for the environment variables common to all of our products.
Select the product whose profile you want to modify from the
simple-syncdirectories in the Server Profiles Repository.
env_varsfile associated with the product and add any of the environment variables you've selected, or change the existing environment variables to fit your purpose.
Modify a Server Profile ¶
You can modify one of our server profiles based on data from your existing Ping Identity product installation. Modify a server profile in either of these ways:
- Using your Github repository
- Using local directories
Using Your Github Repository ¶
We'll use a PingFederate installation as an example. This method uses a server profile provided through a Github URL and assigned to the
SERVER_PROFILE_PATH environment variable (such as,
Export a configuration archive as a *.zip file from a PingFederate installation to a local directory.
Make sure this is exported as a .zip rather than compressing it yourself.
Log in to Github and fork https://github.com/pingidentity/pingidentity-server-profiles into your own GitHub repository.
Open a terminal, create a new directory, and clone your Github repository to a local directory. For example:
mkdir /tmp/pf_to_docker cd /tmp/pf_to_docker git clone https://github.com/<github-username>/pingidentity-server-profiles.git
<github-username>is the name you used to log in to the Github account.
Go to the location where you cloned your fork of our
pingidentity-server-profilesrepository, and replace the
datadirectory you exported from your existing PingFederate installation. For example:
cd pingidentity-server-profiles/getting-started/pingfederate/instance/server/default rm -rf data unzip -qd data <path_to_your_configuration_archive>/data.zip
<path_to_your_configuration_archive>is the location for your exported PingFederate configuration archive.
You now have a local server profile based on your existing PingFederate installation.
Pushing to Github
We recommend you push to Github only what is necessary for your customizations. Our Docker images create the
/opt/outdirectory using a product's base install and layering a profile (set of files) on top.
Push your changes (your local server profile) to the Github repository where you forked our server profile repository. You now have a server profile available through a Github URL.
Deploy the PingFederate container. The environment variables
SERVER_PROFILE_PATHdirect Docker to use the server profile you've modified and pushed to Github.
To save any changes you make after the container is running, add the entry
--volume <local-path>:/opt/outto the
docker runcommand, where <local-path> is a directory you've not already created. See Saving Your Changes for more information.
docker run \ --name pingfederate \ --publish 9999:9999 \ --publish 9031:9031 \ --detach \ --env SERVER_PROFILE_URL=https://github.com/<your_username>/pingidentity-server-profiles.git \ --env SERVER_PROFILE_PATH=getting-started/pingfederate \ --env-file ~/.pingidentity/devops \ pingidentity/pingfederate:edge
If your GitHub server-profile repo is private, use the
username:tokenformat so the container can access the repository. For example,
https://github.com/<your_username>:<your_access_token>/pingidentity-server-profiles.git. See Using Private Github Repositories for more information.
To display the logs as the container starts up, enter:
docker container logs -f pingfederate
In a browser, go to https://localhost:9999/pingfederate/app to display the PingFederate console.
Using Local Directories ¶
This method is particularly helpful when developing locally and the configuration is not ready to be distributed (using Github, for example). We'll use PingFederate as an example. The local directories used by our containers to persist state and data,
/opt/out, will be bound to another local directory and mounted as Docker volumes. This is our infrastructure for modifying the server profile.
Bind Mounts in Production
Docker recommends that you never use bind mounts in a production environment. This method is solely for developing server profiles. See the Docker Documentation for more information.
All configurations and changes during our container runtimes (persisted data) are captured here. For example, the PingFederate image
/opt/out/instancewill contain much of the typical PingFederate root directory:
. ├── README.md ├── SNMP ├── bin ├── connection_export_examples ├── etc ├── legal ├── lib ├── log ├── modules ├── sbin ├── sdk ├── server ├── tools └── work
If a mounted
opt/indirectory exists, our containers will reference this directory at startup for any server profile structures or other relevant files. This method is in contrast to a server profile provided using a Github URL assigned to the
SERVER_PROFILE_PATHenvironment variable (such as,
See Server profile structures for the data each product writes to a mounted
These directories are useful for building and working with local server-profiles. The
/opt/indirectory is particularly valuable if you do not want your containers to access Github for data (the default for our server profiles). Here's an example, again using PingFederate:
Deploy PingFederate using our sample getting-started Server Profile, and mount
/opt/outto a local directory. For example:
docker run \ --name pingfederate \ --publish 9999:9999 \ --detach \ --env SERVER_PROFILE_URL=https://github.com/pingidentity/pingidentity-server-profiles.git \ --env SERVER_PROFILE_PATH=getting-started/pingfederate \ --env-file ~/.pingidentity/devops \ --volume /tmp/docker/pf:/opt/out \ pingidentity/pingfederate:edge
Make sure the local directory (in this case,
/tmp/docker/pf) is not already created. Docker needs to create this directory for the mount to
Go to the mounted local directory (in this case,
/tmp/docker/pf), then make and save some configuration changes to PingFederate using the management console. As you save the changes, you'll be able to see the files in the mounted directory change. For PingFederate, an
instancedirectory is created. This is a PingFederate server profile.
Stop & remove the container and start a new container, adding another
/tmp/docker/pfbind mounted volume, this time to
/opt/in. For example:
docker container rm pingfederate docker run \ --name pingfederate-local \ --publish 9999:9999 \ --detach \ --volume /tmp/docker/pf:/opt/out \ --volume /tmp/docker/pf:/opt/in \ pingidentity/pingfederate:edge
The new container will now use the changes you made using the PingFederate console. In the logs you can see where
sh docker logs pingfederate-local
Finally, stop and remove the new container. Remember your
/tmp/docker/pfdirectory will stay until you remove it (or your machine is rebooted, as this is in /tmp):
docker container rm pingfederate-local
If you also want to remove your work, enter:
rm -rf /tmp/docker/pf