PingIDM

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. 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.

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.

  2. Extract the .zip archive to a working directory:

    unzip ~/Downloads/PingIDM-Admin-UI-8.1.0.zip -d ~/Downloads/tmp

    The archive contains the following structure:

    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 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:

    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 defaults below assume IDM is reachable through the same Nginx host:

    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.

  3. Run the variable replacement script against the compiled JavaScript:

    ./variable_replacement.sh www/platform/js/*.js

  4. Install Nginx using the package manager for your operating system. For example:

    • Debian/Ubuntu

    • RHEL/CentOS/Fedora

    sudo apt update
sudo apt install nginx
    sudo yum install nginx

  5. Copy the UI assets into the Nginx html webroot:

    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
    ...
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:

    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 for guidance on integrating additional server blocks into your existing setup.

  8. Test the modified nginx.conf configuration for syntax errors:

    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:

    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.

  1. Change to the extracted directory:

    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

    docker build -t platform-admin-ui:latest .
    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.

    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 baked into the image, mount it over default.conf at runtime:

    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 above, 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.