--- title: Install the legacy admin UI description: The legacy IDM admin UI is deprecated and will be removed in a future release. Use the Platform admin UI instead. component: pingidm version: 8.1 page_id: pingidm:setup-guide:legacy-admin-ui canonical_url: https://docs.pingidentity.com/pingidm/8.1/setup-guide/legacy-admin-ui.html section_ids: before_you_begin: Before you begin download_and_extract_the_artifact: Download and extract the artifact install_and_configure_nginx: Install and configure Nginx verify_the_installation: Verify the installation --- # Install the legacy admin UI | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------- | | | The legacy IDM admin UI is deprecated and will be removed in a future release. Use the [Platform admin UI](platform-admin-ui.html) instead. | | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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. | Starting with IDM 8.1, the legacy admin UI and API Explorer are no longer bundled with the IDM `.zip` distribution. They are available as a standalone artifact that you deploy behind an Nginx reverse proxy. ## Before you begin * IDM is installed and running on `localhost:8080` (adjust for the host and port of your deployment). * You have administrator privileges to install packages on the host. ## Download and extract the artifact 1. Download the applicable version of the PingIDM Legacy Admin UI `.zip` archive from the [Backstage download site](https://backstage.forgerock.com/downloads). 2. Extract the `.zip` archive: ``` unzip ~/Downloads/PingIDM-Legacy-AdminUI-8.1.0.zip -d /Downloads/tmp/ ``` The archive contains the following structure: ```none PingIDM-Legacy-Admin-UI/ ├── nginx.conf └── www/ ├── admin/ (1) ├── api/ (2) └── errors/ (3) ``` | | | | ----- | ------------------- | | **1** | The legacy admin UI | | **2** | The API Explorer | | **3** | Error pages | ## Install and configure Nginx 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. [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 ``` 2. Copy the contents of the `www/` directory from the PingIDM Legacy Admin UI extracted archive into the Nginx `html` webroot: ```console cp -r ~/Downloads/tmp/PingIDM-Legacy-Admin-UI/www/* /usr/share/nginx/html/ ``` | | | | - | -------------------------------------------------------------------------------------------------------- | | | The default Nginx web root varies by distribution (commonly `/usr/share/nginx/html` or `/var/www/html`). | 3. If you want to disable the API Explorer, delete the `api/` directory from your Nginx `html` webroot. 4. Edit the `nginx.conf` file from the PingIDM Legacy Admin UI extracted archive: 1. Update the `root` directive to point to your Nginx web root. 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`. | 5. Copy the modified `nginx.conf` to the Nginx configuration directory: ```console cp ~/Downloads/tmp/PingIDM-Legacy-Admin-UI/nginx.conf /etc/nginx/nginx.conf ``` | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | If you're already using Nginx for other site configurations, do not 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. | 6. 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 ``` 7. Restart Nginx: ```console systemctl restart nginx ``` ## Verify the installation | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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. | Make sure IDM is running and then go to the UIs: * **Admin UI**: `http://localhost:8082/admin` * **API Explorer**: `http://localhost:8082/api` * **API Explorer (from Admin)**: `http://localhost:8082/admin/#apiExplorer`