--- title: Install the end-user UI description: 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. component: pingidm version: 8.1 page_id: pingidm:setup-guide:idm-enduser-ui canonical_url: https://docs.pingidentity.com/pingidm/8.1/setup-guide/idm-enduser-ui.html section_ids: idm-enduser-ui-prereqs: Before you begin idm-enduser-ui-download: Download and extract the artifact idm-enduser-ui-nginx: Install behind a standalone Nginx server idm-enduser-ui-docker: Install with Docker idm-enduser-ui-access: Access the IDM end-user UI idm-enduser-ui-env-ref: Environment variables reference --- # 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](https://backstage.forgerock.com/downloads), 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 1. Download the IDM end-user UI artifact (`PingIDM-Enduser-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-Enduser-UI-8.1.0.zip -d ~/Downloads/tmp ``` The archive contains the following structure: ```console 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](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/IDMEnduserUI ``` 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_ADMIN_URL= ``` For the full list of supported variables and defaults, refer to [Environment variables reference](#idm-enduser-ui-env-ref). 3. Run the variable replacement script against the compiled JavaScript: ```bash ./variable_replacement.sh www/enduser/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/enduser /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 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`). | 7. Copy the modified `nginx.conf` to the Nginx configuration directory: ```console 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](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/IDMEnduserUI ``` 2. 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 ```bash docker build -t idm-enduser-ui:latest . ``` ```bash docker build \ --build-arg WEB_ROOT_LOCATION=my/assets \ --build-arg NGINX_CONF=my-nginx.conf \ -t idm-enduser-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](#idm-enduser-ui-env-ref). ```bash 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. 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 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 | | --------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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. |