Install the end-user UI

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 IDM end-user UI provides role-based access to self-service tasks and allows users to manage certain aspects of their own accounts. It ships as a separate downloadable artifact from the Backstage download site, and is not bundled with the IDM .zip.

You can deploy the IDM end-user 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.

Before you begin

Before you install the end-user UI, make sure you have the following:

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

Download the IDM end-user UI artifact (PingIDM-Enduser-UI-8.1.0.zip) from the Backstage download site.

Extract the .zip archive to a working directory:

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

The archive contains the following structure:

IDMEnduserUI/
├── www/
│   └── enduser/              # 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/.

Change to the extracted directory:
```
cd ~/Downloads/tmp/IDMEnduserUI
```
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:
```
export IDM_REST_URL=/openidm
export IDM_ADMIN_URL=
```
For the full list of supported variables and defaults, refer to Environment variables reference.
Run the variable replacement script against the compiled JavaScript:
```
./variable_replacement.sh www/enduser/js/*.js
```
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
Copy the UI assets into the Nginx html webroot:
```
cp -r www/enduser /usr/share/nginx/html/
```
The default Nginx webroot varies by distribution (commonly /usr/share/nginx/html or /var/www/html).

Edit the nginx.conf file from the extracted archive:

Update the root directive to point to your Nginx webroot. For example, /usr/share/nginx/html.

Update the proxy_pass directive to point to your IDM instance. For example, http://localhost:8080/openidm.

Example nginx.conf excerpt

...
server {
    listen       8083;        (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 `8083` to avoid conflicts with IDM (port `8080`) and the admin UI (port `8082`).

Copy the modified nginx.conf to the Nginx configuration directory:

cp ~/Downloads/tmp/IDMEnduserUI/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.

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

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.

Change to the extracted directory:
```
cd ~/Downloads/tmp/IDMEnduserUI
```
From the extracted archive, build the image.

The Dockerfile accepts two optional build arguments:

Argument Default Description

WEB_ROOT_LOCATION

www/enduser

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 idm-enduser-ui:latest .
docker build \ --build-arg WEB_ROOT_LOCATION=my/assets \ --build-arg NGINX_CONF=my-nginx.conf \ -t idm-enduser-ui:latest .
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-enduser -p 8083:8080 \
  -e IDM_REST_URL="/openidm" \
  -e IDM_ADMIN_URL="" \
  idm-enduser-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.

Argument	Default	Description
`WEB_ROOT_LOCATION`	`www/enduser`	Path to the built UI assets
`NGINX_CONF`	`nginx.docker.conf`	Server block config to copy into the image.

To use your own Nginx server block instead of the one built into the image, mount it over default.conf at runtime:

docker run -d -p 8083:8080 \
  -v /path/to/my-nginx.conf:/etc/nginx/conf.d/default.conf:ro \
  idm-enduser-ui:latest

Access the IDM end-user 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:8083

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

Variable	Default	Description
`IDM_REST_URL`	`/openidm`	IDM REST API URL
`IDM_ADMIN_URL`	(empty)	IDM admin console URL. Set to the URL of your admin UI (for example, `http://localhost:8082/platform`). Leave blank if you don’t need a link to the admin console from the end-user UI.

IDM_REST_URL

/openidm

IDM REST API URL

IDM_ADMIN_URL

(empty)

IDM admin console URL. Set to the URL of your admin UI (for example, http://localhost:8082/platform). Leave blank if you don’t need a link to the admin console from the end-user UI.