--- title: Install and run IDM description: Use the procedures in this section to install, start, run, and stop IDM. component: pingidm version: 8.1 page_id: pingidm:install-guide:chap-install canonical_url: https://docs.pingidentity.com/pingidm/8.1/install-guide/chap-install.html keywords: ["Installation", "Startup", "Shutdown", "Uninstall", "Debug"] section_ids: install-openidm: Install IDM run-openidm: Start IDM run_idm_as_a_background_process: Run IDM as a background process stop-openidm: Stop IDM chap-uninstall: Uninstall IDM starting-in-debug-mode: Start IDM in debug mode change-jvm-heap: Change the JVM heap size --- # Install and run IDM Use the procedures in this section to install, start, run, and stop IDM. | | | | - | ------------------------------------------------------------------------------------------- | | | Before you can use IDM, you must [select and configure a repository](chap-repository.html). | ## Install IDM Follow these steps to install IDM: 1. Make sure you have an appropriate version of Java installed: ```console java -version openjdk version "21.0.9" 2025-10-21 LTS OpenJDK Runtime Environment Temurin-21.0.9+10 (build 21.0.9+10-LTS) OpenJDK 64-Bit Server VM Temurin-21.0.9+10 (build 21.0.9+10-LTS, mixed mode, sharing) ``` For a description of the Java requirements, refer to [Before you install](../release-notes/before-you-install.html). 2. []()Download IDM from [Backstage](https://backstage.forgerock.com/downloads/). 3. Unpack the contents of the .zip file into the install directory: ``` unzip ~/Downloads/IDM-8.1.0.zip Archive: IDM-8.1.0.zip inflating: openidm/.checksums.csv creating: openidm/bundle/ extracting: openidm/bundle/openidm-audit-8.1.0.jar ... ``` 4. By default, IDM listens for HTTP and HTTPS connections on ports 8080 and 8443, respectively. To change these port numbers, edit the following settings in your `resolver/boot.properties` file: * `openidm.port.http` * `openidm.port.https` When you deploy IDM in production, you *must* set `openidm.host` to the URL of your deployment in the `resolver/boot.properties` file. Otherwise, calls to the `/admin` endpoint are not properly redirected. Deployment URLs will vary, depending on whether you're using a load balancer. While IDM documentation does not specify how you'd configure a load balancer, you'll need to configure IDM in a cluster as described in [IDM cluster configuration](cluster-config.html), and specifically in [Deploy Securely Behind a Load Balancer](../security-guide/chap-connections.html#clustering-load-balancer). ## Start IDM | | | | - | ------------------------------------------------------------------------------------------------------- | | | To adjust the JVM heap size before starting IDM, refer to [Change the JVM heap size](#change-jvm-heap). | Follow these steps to run IDM interactively: 1. Start the Felix container, load all services, and start a command shell to allow you to manage the container: * Bash * PowerShell ``` /path/to/openidm/startup.sh Using OPENIDM_HOME: /path/to/openidm Using PROJECT_HOME: /path/to/openidm Using OPENIDM_OPTS: -Xmx2048m -Xms2048m \... -> OpenIDM version "8.1.0" OpenIDM ready ``` ``` \path\to\openidm\startup.bat "Using OPENIDM_HOME: \path\to\openidm" "Using PROJECT_HOME: \path\to\openidm" "Using OPENIDM_OPTS: -Xmx2048m -Xms2048m -Dfile.encoding=UTF-8" \... -> OpenIDM version "8.1.0" OpenIDM ready ``` 2. At the OSGi console `->` prompt, you can enter commands, such as `help` for usage or `ps` to view the bundles installed. Startup errors and messages are logged to the console by default. You can also view these messages in the log files at `/path/to/openidm/logs`. ## Run IDM as a background process You can also start IDM as a background process on UNIX and Linux systems. Follow these steps, preferably before you start IDM for the first time: 1. If you have already started the server, shut it down and remove the Felix cache files under `openidm/felix-cache/` : ``` shutdown ... rm -rf felix-cache/* ``` 2. Start the server in the background. The `nohup` survives a logout, and the `2>&1&` redirects standard output and standard error to the noted `console.out` file: ``` nohup ./startup.sh > logs/console.out 2>&1& [1] 2343 ``` To stop the server running as a background process, use the `shutdown.sh` script: ``` ./shutdown.sh Stopping OpenIDM (2343) ``` | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Although installations on macOS systems are not supported in production, you might want to run IDM on macOS in a demo or test environment. To run IDM in the background on a macOS system, take the following additional steps:- Remove the `org.apache.felix.shell.tui-*.jar` bundle from the `openidm/bundle` directory. - Disable [ConsoleHandler logging](../monitoring-guide/server-logs.html#log-disabling). | ## Stop IDM You can stop IDM from the `->` prompt in the OSGi console. 1. In the OSGi console, enter the `shutdown` command at the `->` prompt. 2. On Unix systems, you can stop IDM by using the `shutdown.sh` script: ``` /path/to/openidm/shutdown.sh Stopping OpenIDM (31391) ``` ## Uninstall IDM 1. Stop the server if it is running, as described in [Stop IDM](#stop-openidm). 2. Remove the directory where you installed the software: ``` rm -rf /path/to/openidm ``` 3. If you use a JDBC database for the repository, drop the `openidm` database. ## Start IDM in debug mode To debug custom libraries, start the server with the Java Platform Debugger Architecture (JPDA): 1. Start IDM with the `jpda` option: ``` /path/to/openidm/startup.sh jpda Executing ./startup.sh... Using OPENIDM_HOME: /path/to/openidm Using OPENIDM_OPTS: -Xmx2048m -Xms2048m -Djava.compiler=NONE -Xnoagent -Xdebug -Xrunjdwp:transport=dt_socket,address=5005,server=y,suspend=n ... Listening for transport dt_socket at address: 5005 Using boot properties at /path/to/openidm/resolver/boot.properties -> OpenIDM version "8.1.0" (revision: xxxx) OpenIDM ready ``` The relevant JPDA options are listed in the startup script (`startup.sh`). 2. In your IDE, attach a Java debugger to the JVM via socket on port 5005. | | | | - | -------------------------------------------------------------------------------------------------------- | | | This interface is internal and subject to change. If you depend on this interface, contact Ping support. | ## Change the JVM heap size Changing the JVM heap size can improve performance and reduce the time it takes to run reconciliations. You can set the JVM heap size via the `OPENIDM_OPTS` environment variable. If `OPENIDM_OPTS` is undefined, the JVM maximum heap size defaults to 2GB. For example, to set the minimum and maximum heap sizes to 4GB, enter the following before starting IDM: * Unix/Linux * Windows ``` cd /path/to/openidm/ export OPENIDM_OPTS="-Xms4096m -Xmx4096m" ./startup.sh Using OPENIDM_HOME: /path/to/openidm Using PROJECT_HOME: /path/to/openidm Using OPENIDM_OPTS: -Xms4096m -Xmx4096m ... OpenIDM ready ``` ``` cd \path\to\openidm set OPENIDM_OPTS=-Xms4096m -Xmx4096m startup.bat "Using OPENIDM_HOME: \path\to\openidm" "Using PROJECT_HOME: \path\to\openidm" "Using OPENIDM_OPTS: -Xms4096m -Xmx4096m -Dfile.encoding=UTF-8" ... OpenIDM ready ``` You can also edit the `OPENIDM_OPTS` values in `startup.sh` or `startup.bat`. | | | | - | ------------------------------------------------------------------------------------------------------------------ | | | For more information about tuning and load testing, refer to [Load testing](../monitoring-guide/load-testing.html) |