Install and Run IDM

Use the procedures in this section to install, start, run, and stop IDM.

Follow these steps to install IDM:

  1. Make sure you have an appropriate version of Java installed:

    java -version
    openjdk version "11.0.6" 2020-01-14
    OpenJDK Runtime Environment AdoptOpenJDK (build 11.0.6+10)
    OpenJDK 64-Bit Server VM AdoptOpenJDK (build 11.0.6+10, mixed mode)

    For a description of the Java requirements, see Before You Install.

  2. Download IDM from the ForgeRock BackStage download site. Releases on the ForgeRock BackStage download site are thoroughly validated for ForgeRock customers who run the software in production deployments, and for those who want to try or test a given release.

  3. Unpack the contents of the .zip file into the install directory:

    unzip ~/Downloads/IDM-7.0.2.zip
    Archive:  IDM-7.0.2.zip
      inflating: openidm/.checksums.csv
       creating: openidm/bundle/
     extracting: openidm/bundle/openidm-audit-7.0.2.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 same 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 "Configure an IDM Instance as Part of a Cluster", and specifically in "Deploy Securely Behind a Load Balancer".

  5. Before running IDM in production, replace the default embedded DS repository with a supported repository.

    For more information, see Select a Repository.

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:

    /path/to/openidm/startup.sh
    
    Using OPENIDM_HOME:   /path/to/openidm
    Using PROJECT_HOME:   /path/to/openidm
    Using OPENIDM_OPTS:   -Xmx1024m -Xms1024m
    Using LOGGING_CONFIG: -Djava.util.logging.config.file=/path/to/openidm/conf/logging.properties
    -> OpenIDM version "7.0.2"
    OpenIDM ready
    \path\to\openidm\startup.bat
    
    "Using OPENIDM_HOME:   \path\to\openidm"
    "Using PROJECT_HOME:   \path\to\openidm"
    "Using OPENIDM_OPTS:   -Xmx1024m -Xms1024m -Dfile.encoding=UTF-8"
    "Using LOGGING_CONFIG: -Djava.util.logging.config.file=\path\to\openidm\conf\logging.properties"
    -> OpenIDM version "7.0.2"
    OpenIDM ready

    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.

  2. Alternatively, you can manage the container and services from the Apache Felix Web Console.

    Use these hints to connect to the Apache Felix Web Console:

    Select Main > Components to see core services and their respective states.

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)

Note

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.

You can stop IDM from the -> prompt in the OSGi console, or through the Apache Felix Web Console. Both of these options stop the Felix container.

  1. In the OSGi console, enter the shutdown command at the -> prompt.

  2. In the Apache Felix Web Console, select Web Console > System Information to stop the container.

  3. On Unix systems, you can stop IDM by using the shutdown.sh script:

    /path/to/openidm/shutdown.sh
    Stopping OpenIDM (31391)
  1. Stop the server if it is running, as described in Stop IDM.

  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.

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:   -Xmx1024m -Xms1024m -Djava.compiler=NONE -Xnoagent -Xdebug
     -Xrunjdwp:transport=dt_socket,address=5005,server=y,suspend=n
    Using LOGGING_CONFIG:
       -Djava.util.logging.config.file=/path/to/openidm/conf/logging.properties
    Listening for transport dt_socket at address: 5005
    Using boot properties at /path/to/openidm/resolver/boot.properties
    -> OpenIDM version "7.0.2" (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.

Caution

This interface is internal and subject to change. If you depend on this interface, contact ForgeRock support.

Read a different version of :