Customizing Server Profiles ¶
When you deployed the full stack of product containers in Getting Started, you used the server profiles associated with each of our products. In the YAML files, you'll see entries like the following 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 previous example, 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. You can find environment variables that are common to all product images in the PingBase Image Directory. There are also product-specific environment variables. You can find these in the Docker Image Information for each available product.
Before you begin ¶
- Complete Get Started to set up your DevOps environment and run a test deployment of the products.
- Understand the Anatomy of the Product Containers.
About this task ¶
Add or change the environment variables used for any of our server profiles to better fit your purposes.
You can find these variables in the Server Profiles Repository for each product.
For example, the location for the
env_varsfile 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 either:
- Forking our server profiles repository (
https://github.com/pingidentity/pingidentity-server-profiles) to your Github repository
- Using local directories
- Forking our server profiles repository (
Adding or Changing Environment Variables ¶
Select any environment variables to add from either:
simple-syncdirectories in the Server Profiles Repository, select the product whose profile you want to modify.
env_varsfile associated with the product and either:
- Add any of the environment variables you've selected.
- Change the existing environment variables to fit your purpose.
Modifying 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 by either:
- Using your Github repository
- Using local directories
Using Your Github Repository ¶
In this example PingFederate installation, using the Github Repository 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.
Sign on 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 sign on 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
You should 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.
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 haven't already created. For more information, see Saving Your Changes.
As in this example, the environment variables
SERVER_PROFILE_PATHdirect Docker to use the server profile you've modified and pushed to Github:
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/config \ 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. For more information, see Using Private Github Repositories.
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 isn't 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. For more information, see the Docker Documentation.
All configurations and changes during our container runtimes (persisted data) are captured here. For example, the PingFederate image
/opt/out/instancecontains 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 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,
For the data each product writes to a mounted
/opt/indirectory, see Server profile structures.
These directories are useful for building and working with local server-profiles. The
/opt/indirectory is particularly valuable if you don't want your containers to access Github for data (the default for our server profiles).
The following example deployment uses PingFederate.
Deploy PingFederate using our sample getting-started Server Profile, and mount
/opt/outto a local directory:
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/config \ --volume /tmp/docker/pf:/opt/out \ pingidentity/pingfederate:edge
Make sure the local directory (in this case,
/tmp/docker/pf) isn't 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 and remove the container and start a new container, adding another
/tmp/docker/pfbind mounted volume, this time to
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
Stop and remove the new container.
/tmp/docker/pfdirectory will stay until you remove it (or until your machine is rebooted because this is in the
docker container rm pingfederate-local
If you also want to remove your work, enter:
rm -rf /tmp/docker/pf