--- title: Install the Platform admin UI for standalone IDM description: The Platform admin UI is the replacement for the deprecated legacy admin UI. Starting with IDM 8.1, it ships as a separate downloadable artifact from the Backstage download site, and is not bundled with the IDM .zip. component: pingidm version: 8.1 page_id: pingidm:setup-guide:platform-admin-ui canonical_url: https://docs.pingidentity.com/pingidm/8.1/setup-guide/platform-admin-ui.html section_ids: platform-admin-ui-prereqs: Before you begin platform-admin-ui-download: Download and extract the artifact platform-admin-ui-nginx: Install behind a standalone Nginx server platform-admin-ui-docker: Install with Docker platform-admin-ui-access: Access the Platform admin UI platform-admin-ui-env-ref: Environment variables reference --- # Install the Platform admin UI for standalone IDM | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | To use any IDM UI in a production environment, it must only be accessed in an HTTPS context. You can accomplish this using a separate server (such as an SSL-terminating reverse proxy) or directly configuring the web server hosting the UI files to support HTTPS. The specific implementation choice for using HTTPS is outside the scope of this documentation. | The Platform admin UI is the replacement for the [deprecated legacy admin UI](legacy-admin-ui.html). Starting with IDM 8.1, it ships as a separate downloadable artifact from the [Backstage download site](https://backstage.forgerock.com/downloads), and is not bundled with the IDM `.zip`. You can deploy the Platform admin UI in either of two ways from the same artifact: * Behind a standalone Nginx server. * As a Docker container you build from the included `Dockerfile`. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The Platform admin UI and the legacy admin UI are independent artifacts. You can install one or both on different Nginx servers or different ports. New deployments should use the Platform admin UI. | ## Before you begin * IDM 8.1 or later, running and reachable from the host that serves the UI. * For the Nginx path: Nginx 1.18 or later. * For the Docker path: Docker 20.10 or later. ## Download and extract the artifact 1. Download the Platform admin UI artifact (`PingIDM-Admin-UI-8.1.0.zip`) from the [Backstage download site](https://backstage.forgerock.com/downloads). 2. Extract the `.zip` archive to a working directory: ```bash unzip ~/Downloads/PingIDM-Admin-UI-8.1.0.zip -d ~/Downloads/tmp ``` The archive contains the following structure: ```console IDMAdminUI/ ├── www/ │ └── platform/ # Production build output ├── Dockerfile # Production image (Nginx + Alpine) ├── nginx.conf # Example config for standalone Nginx ├── nginx.docker.conf # Example config for Docker ├── entrypoint.sh # Container entrypoint ├── variable_replacement.sh # envsubst script for static assets └── DEPLOYMENT.md ``` ## Install behind a standalone Nginx server Use this path when you want to serve the UI directly from Nginx without Docker. Consult the [Nginx documentation](https://nginx.org/en/docs/) for your operating system, as you might need to adjust the instructions in this overview. Examples include nesting the `server` block inside the `http` block of your main `/etc/nginx/nginx.conf` or placing `nginx.conf` as a standalone file in `/etc/nginx/conf.d/`. 1. Change to the extracted directory: ```bash cd ~/Downloads/tmp/IDMAdminUI ``` 2. Set the environment variables for your deployment. The `variable_replacement.sh` script substitutes these values into the compiled JavaScript bundles. The following defaults assume IDM is reachable through the same Nginx host: ```bash export IDM_REST_URL=/openidm export IDM_UPLOAD_URL=/upload export IDM_EXPORT_URL=/export export MENUS_FILE=menus.idm export ROUTES_FILE=routes.idm export DEPLOYMENT_TYPE=IDM export ENABLE_WORKFORCE=false export AM_URL= export AM_ADMIN_URL= ``` For the full list of supported variables and defaults, refer to [Environment variables reference](#platform-admin-ui-env-ref). 3. Run the variable replacement script against the compiled JavaScript: ```bash ./variable_replacement.sh www/platform/js/*.js ``` 4. [Install Nginx](https://nginx.org/en/docs/install.html) using the package manager for your operating system. For example: * Debian/Ubuntu * RHEL/CentOS/Fedora ```console sudo apt update sudo apt install nginx ``` ```console sudo yum install nginx ``` 5. Copy the UI assets into the Nginx `html` webroot: ```bash cp -r www/platform /usr/share/nginx/html/ ``` | | | | - | ------------------------------------------------------------------------------------------------------- | | | The default Nginx webroot varies by distribution (commonly `/usr/share/nginx/html` or `/var/www/html`). | 6. Edit the `nginx.conf` file from the extracted archive: 1. Update the `root` directive to point to your Nginx webroot. For example, `/usr/share/nginx/html`. 2. Update the `proxy_pass` directive to point to your IDM instance. For example, `http://localhost:8080/openidm`. Example `nginx.conf` excerpt ```nginx ... server { listen 8082; (1) server_name localhost; root /usr/share/nginx/html; ... location /openidm { proxy_pass http://localhost:8080/openidm; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } } ``` | | | | ----- | --------------------------------------------------------------------------------------------------- | | **1** | The server listens on port `8082` to avoid conflicts with IDM, which typically runs on port `8080`. | 7. Copy the modified `nginx.conf` to the Nginx configuration directory: ```console cp ~/Downloads/tmp/IDMAdminUI/nginx.conf /etc/nginx/nginx.conf ``` | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you're already using Nginx for other site configurations, don't overwrite your existing `nginx.conf`. Read about [managing Nginx configuration files](https://docs.nginx.com/nginx/admin-guide/basic-functionality/managing-configuration-files/) for guidance on integrating additional server blocks into your existing setup. | 8. Test the modified `nginx.conf` configuration for syntax errors: ```console nginx -t nginx: the configuration file /etc/nginx/nginx.conf syntax is ok nginx: configuration file /etc/nginx/nginx.conf test is successful ``` 9. Restart Nginx: ```console systemctl restart nginx ``` ## Install with Docker Use this path when you want to run the UI as a container. The included `Dockerfile` produces a production image based on `nginxinc/nginx-unprivileged`. You can download Docker from [the official Docker homepage](https://www.docker.com). 1. Change to the extracted directory: ```bash cd ~/Downloads/tmp/IDMAdminUI ``` 2. From the extracted archive, build the image. The `Dockerfile` accepts two optional build arguments: | Argument | Default | Description | | ------------------- | ------------------- | ------------------------------------------- | | `WEB_ROOT_LOCATION` | `www/platform` | Path to the built UI assets | | `NGINX_CONF` | `nginx.docker.conf` | Server block config to copy into the image. | * Build without arguments * Build with arguments ```bash docker build -t platform-admin-ui:latest . ``` ```bash docker build \ --build-arg WEB_ROOT_LOCATION=my/assets \ --build-arg NGINX_CONF=my-nginx.conf \ -t platform-admin-ui:latest . ``` 3. Run the container, passing your environment variables as `-e` flags. For the full list of supported variables and defaults, refer to [Environment variables reference](#platform-admin-ui-env-ref). ```bash docker run -d --name idm-admin -p 8082:8080 \ -e IDM_REST_URL="/openidm" \ -e IDM_UPLOAD_URL="/upload" \ -e IDM_EXPORT_URL="/export" \ -e MENUS_FILE="menus.idm" \ -e ROUTES_FILE="routes.idm" \ -e DEPLOYMENT_TYPE="IDM" \ -e ENABLE_WORKFORCE="false" \ -e AM_URL="" \ -e AM_ADMIN_URL="" \ platform-admin-ui:latest ``` The Docker entrypoint runs `variable_replacement.sh` against the compiled bundles before starting Nginx, so the UI picks up your runtime values without rebuilding the image. 4. To use your own Nginx server block instead of the one built into the image, mount it over `default.conf` at runtime: ```bash docker run -d -p 8082:8080 \ -v /path/to/my-nginx.conf:/etc/nginx/conf.d/default.conf:ro \ platform-admin-ui:latest ``` ## Access the Platform admin UI With IDM running, go to the Nginx host and port you configured. For the defaults shown previously, the UI is available at: `http://localhost:8082/platform` ## Environment variables reference The entrypoint passes every variable in the following table through `envsubst` and into the compiled JavaScript bundles. Build the image (or extract the artifact) once, then configure per environment. | Variable | Default | Description | | ------------------ | ------------ | ------------------------------------------------------- | | `IDM_REST_URL` | `/openidm` | IDM REST API URL | | `IDM_UPLOAD_URL` | `/upload` | IDM upload URL | | `IDM_EXPORT_URL` | `/export` | IDM export URL | | `MENUS_FILE` | `menus.idm` | IDM menus file | | `ROUTES_FILE` | `routes.idm` | IDM routes file | | `DEPLOYMENT_TYPE` | `IDM` | Deployment type. Leave set to `IDM` for standalone IDM. | | `ENABLE_WORKFORCE` | `false` | Workforce features. Leave `false` for standalone IDM. | | `AM_URL` | *(empty)* | PingAM URL. Leave blank for standalone IDM. | | `AM_ADMIN_URL` | *(empty)* | PingAM admin URL. Leave blank for standalone IDM. |