--- title: Common manage-profile workflows description: You can use the manage-profile tool to complete a variety of workflows in PingAuthorize. component: pingauthorize version: 11.0 page_id: pingauthorize:pingauthorize_server_administration_guide:paz_workflows canonical_url: https://docs.pingidentity.com/pingauthorize/11.0/pingauthorize_server_administration_guide/paz_workflows.html revdate: April 28, 2025 section_ids: create_server_profile: Creating a server profile about-this-task: About this task steps: Steps example: Example: example-2: Example: choose-from: Choose from: install_new_env: Installing a new environment before-you-begin: Before you begin about-this-task-2: About this task steps-2: Steps example-3: Example: example-4: Example: example-5: Example: scaling_up_server_env: Scaling up your environment about-this-task-3: About this task manage_replace_profile: Rolling out an update before-you-begin-2: Before you begin about-this-task-4: About this task steps-3: Steps example-6: Example: example-7: Example: example-8: Example: --- # Common manage-profile workflows You can use the `manage-profile` tool to complete a variety of workflows in PingAuthorize. This section describes how to use the `manage-profile` tool to accomplish typical server-management tasks, like the following examples: * [Creating a server profile](#create_server_profile) * [Installing a new environment](#install_new_env) * [Scaling up your environment](#scaling_up_server_env) * [Rolling out an update](#manage_replace_profile) The following sections describe these tasks in more detail. For more information about the `manage-profile` tool, run `manage-profile --help`. For more information about each individual subcommand and its options, run `manage-profile --help`. ## Creating a server profile You can create a server profile from a configured server in PingAuthorize Server. ### About this task To create a server profile from a configured server, use the `generate-profile` subcommand. ### Steps 1. Create a profile directory. #### Example: ```shell $ mkdir -p /opt/server-profiles/pingauthorize ``` 2. Run `generate-profile`. #### Example: ```shell $ bin/manage-profile generate-profile --profileRoot /opt/server-profiles/pingauthorize ``` 3. Customize the resulting profile to suit your needs and to remove deployment environment-specific values. #### Choose from: * Specify a consistent location for the license key file: 1. Copy the license key file to the server profile's `misc-files` directory. ```shell $ cp {pingauthorize}.lic /opt/server-profiles/pingauthorize/misc-files/ ``` 2. Open the `setup-arguments.txt` file in a standard text editor. 3. Locate the `--licenseKeyFile` argument. 4. Change the value of `--licenseKeyFile` to the following value. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | Use `PING_PROFILE_ROOT` only with files that are not needed after initial setup, such as password files in `setup-arguments.txt`. Do not use the `PING_PROFILE_ROOT` variable for files needed while the server is running. The `manage-profile` tool creates a temporary copy of the server profile that is deleted after the tool completes, so files are not accessible under `PING_PROFILE_ROOT` when the server is running. For files you need while the server is running, such as keystore and truststore files, copy the files into the server root using the profile's `server-root/pre-setup` directory, and then refer to the files using with the `PING_SERVER_ROOT` variable. | ```shell ${PING_PROFILE_ROOT}/misc-files/{pingauthorize}.lic ``` 5. Save your changes. * Remove deployment environment-specific values and replace them with variables. For example, to refer to a different PingFederate server in your development environments versus your test environments, perform the following steps: 1. Open the `/opt/server-profiles/pingauthorize/dsconfig/00-config.dsconfig` file in a standard text editor. 2. Locate the value specified for `base-url` for the external server that identifies your PingFederate server. 3. Replace the value with a variable, like `${PF_BASE_URL}`. 4. Save your changes. 5. Create or update a server profile variables file for your development environment. 6. Add a row like the following example to the variables file. ``` PF_BASE_URL=https://sso.dev.example.com:9031 ``` 7. Save your changes. 8. Continue replacing deployment environment-specific values with variables until the server profile contains no more deployment environment-specific values. At this point, you can check the server profile in to a version-control system, like Git, share with your team, and integrate into your deployment automation. ## Installing a new environment You can use `manage-profile setup` to set up a new server instance and deployment environment in PingAuthorize Server. ### Before you begin The steps in this section make the following assumptions: * A server profile has already been created at the path `~/git/server-profiles/pingauthorize`. * Your development environment's variables file is saved at the path `~/pingauthorize-variables-dev.env`. ### About this task After you create and customize a server profile, use the `manage-profile setup` subcommand to set up new server instances and additional deployment environments. The `setup` subcommand completes the following tasks: * Copies the server root files * Runs the `setup` tool * Runs the dsconfig batch files * Installs the server SDK extensions * Sets the server's cluster name to a unique value | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Cluster-wide configuration is automatically mirrored across all servers in the topology with the same cluster name. In a DevOps deployment with immutable servers, configuration mirroring introduces risk. Therefore, in most cases, cluster names should be unique for each server to avoid configuration mirroring. | ### Steps 1. Extract the contents of the compressed archive to a directory of your choice. #### Example: ```shell $ mkdir /opt/pingauthorize $ cd /opt/pingauthorize $ unzip {pingauthorize}-.zip ``` 2. Change directories. #### Example: ```shell $ cd {pingauthorize} ``` 3. Run `setup`. #### Example: ```shell $ bin/manage-profile setup \ --profile ~/git/server-profiles/pingauthorize \ --profileVariablesFile ~/pingauthorize-variables-dev.env ``` ## Scaling up your environment You can scale up the environment in your PingAuthorize Server instance. ### About this task The automation for this task is identical to the previous task of installing a new server in a new environment. Because each instance of PingAuthorize Server requires a unique instance name and host name, each instance must also be set up from a unique server profile variables file. ## Rolling out an update When you roll out a PingAuthorize Server update, run `manage-profile replace-profile` to use a server profile that you have set up. ### Before you begin The steps in this section make the following assumptions: * A server profile has been created at the path `~/git/server-profiles/pingauthorize`. * The server's server profile variables file is saved at the path `/opt/pingauthorize/pingauthorize-variables.env`. * The existing server with the earlier configuration is installed at `/opt/pingauthorize/PingAuthorize`. ### About this task Run the `replace-profile` subcommand on a server that was originally set up with a server profile to replace its configuration with a new profile. The `replace-profile` subcommand applies a specified server profile to an existing server while also preserving its configuration. While `manage-profile replace-profile` is running, the existing server is stopped and moved to a temporary directory that the `--tempServerDirectory` argument specifies. A fresh, new server is subsequently installed and set up with the new profile. If the final server was running before the command was started, it is left running. If the final server was stopped, it remains stopped. If files have been added or modified in the server root since you ran the most recent `manage-profile setup` or `manage-profile replace-profile` subcommand, they are included in the final server with the replaced profile. Otherwise, files added specifically from the `server-root` directory of the previous server profile are absent from the final server with the replaced profile. If errors occur while running the subcommand, such as the new profile having an invalid `setup-arguments.txt` file, the existing server returns to its original state from before you ran `manage-profile replace-profile`. ### Steps 1. Extract the distribution package for the same or a new version of PingAuthorize Server to a location outside the existing server's installation. #### Example: ```shell $ mkdir ~/stage $ cd ~/stage $ unzip {pingauthorize}-.zip ``` 2. Change directories. You must run the `replace-profile` subcommand from the location of the distribution package, not from the existing server. #### Example: ```shell $ cd {pingauthorize} ``` 3. Run `replace-profile`. #### Example: ```shell $ bin/manage-profile replace-profile \ --serverRoot /opt/pingauthorize/{pingauthorize} \ --profile ~/git/server-profiles/pingauthorize \ --profileVariablesFile ~/pingauthorize-variables-dev.env ```