Downloading and Starting IG

The following sections describe options for downloading and starting IG. For information about other installation options, such as setting the default location of the configuration folders, and configuring for HTTPS, see the Installation Guide.

Download and Start IG in Standalone Mode

Consider the following best practices for installing and running IG:

  • Create a service account with which to install and run IG, for example, igadmin. Do not use the root account to install and run IG.

  • Allocate the following permissions to the account:

    • Read/write permissions on the installation directory, for example /path/to/identity-gateway.

    • Execute permissions on the scripts in the installation bin directory, for example /path/to/identity-gateway/bin.

The following sections describe how to install and start IG in standalone mode, from a .zip file.

Download the IG .zip File

  1. Create a local installation directory for IG. The examples in this section use /path/to.

  2. Download IG-7.1.0.zip from the ForgeRock BackStage download site, and copy the .zip file to the installation directory:

    $ cp IG-7.1.0.zip /path/to/IG-7.1.0.zip
  3. Unzip the file:

    $ unzip IG-7.1.0.zip

    The directory /path/to/identity-gateway is created.

Start IG With Default Settings

Use the following step to start the instance of IG, specifying the configuration directory where IG looks for configuration files.

  1. Start IG:

    $ /path/to/identity-gateway/bin/start.sh
    
    ...
    ... started in 1234ms on ports : [8080]

    By default, the base location for IG configuration files is in $HOME/.openig.

    To read the configuration from a different location, specify the base location as an argument. The following example reads the configuration from the config directory under /path/to/instance-dir:

    $ /path/to/identity-gateway/bin/start.sh /path/to/instance-dir
  2. Check that IG is running in one of the following ways:

    • Ping IG at http://openig.example.com:8080/openig/ping, and make sure an HTTP 200 is returned.

    • Access the IG welcome page at http://openig.example.com:8080.

    • When IG is running in development mode, display the product version and build information at http://openig.example.com:8080/openig/api/info.

Start IG With Custom Settings

By default, IG runs on HTTP, on port 8080, from the instance directory $HOME/.openig.

To start IG with custom settings, add the configuration file admin.json with the following properties, and restart IG:

  • vertx: Finely tune Vert.x instances.

  • connectors: Customize server port, TLS, and Vert.x-specific configurations. Each connectors object represents the configuration of an individual port.

  • prefix: Set the instance directory, and therefore, the base of the route for administration requests.

The following example starts IG on non-default ports, and configures Vert.x-specific options for the connection on port 9091:

{
  "connectors": [{
    "port": 9090
  },
  {
    "port": 9091,
    "vertx": {
      "maxWebSocketFrameSize": 128000,
      "maxWebSocketMessageSize": 256000,
      "compressionLevel": 4
    }
  }]
}

For more information, see AdminHttpApplication (admin.json).

Stop IG

  1. In the terminal where IG is running, select CTRL+C to stop the service.

Downloading and Starting IG in Tomcat

The commands in this guide assume that you install Tomcat to /path/to/tomcat, and after installation, you have a directory /path/to/tomcat/webapps in which you install IG. If you use another directory structure, substitute the commands.

  1. Download a supported version of Tomcat server from its download page, and install it to /path/to/tomcat.

  2. Remove the ROOT directory in Tomcat:

    $ rm -rf /path/to/tomcat/webapps/ROOT
  3. Download IG-7.1.0.war from the ForgeRock BackStage download site.

  4. Copy the IG-7.1.0.war to the Tomcat webapps directory, as ROOT.war:

    $ cp IG-7.1.0.war /path/to/tomcat/webapps/ROOT.war

    Tomcat automatically deploys IG in the root context on startup.

  5. Start Tomcat:

    $ /path/to/tomcat/bin/startup.sh

    If necessary, make the startup scripts executable.

  6. Check that IG is running in one of the following ways:

Downloading and Starting IG in Jetty

The commands in this guide assume that you install Jetty to /path/to/jetty, and after installation, you have a directory /path/to/jetty/webapps in which you install IG. If you use another directory structure, substitute the commands.

  1. Download a supported version of Jetty server from its download page, and install it to /path/to/jetty.

  2. Download IG-7.1.0.war from the ForgeRock BackStage download site.

  3. Copy the .war file:

    $ cp IG-7.1.0.war /path/to/jetty/webapps/IG-7.1.0.war

    Jetty automatically deploys IG in the root context on startup.

  4. Start Jetty:

    • To start Jetty in the background, enter:

      $ /path/to/jetty/bin/jetty.sh start
    • To start Jetty in the foreground, enter:

      $ cd /path/to/jetty/
      $ java -jar start.jar
  5. Check that IG is running in one of the following ways:

Download and Start IG in JBoss EAP

This section installs JBoss to /path/to/jboss. If you use another directory structure, substitute the commands.

  1. Download a supported version of JBoss server from its download page, and install it to /path/to/jboss.

  2. In the JBoss configuration file /path/to/jboss/standalone/configuration/standalone.xml, delete the line for the JBoss welcome-content handler:

    <server name="default-server">
      <host name="default-host" alias="localhost">
        <location name="/" handler="welcome-content"/> <!-- Delete this line -->
  3. Download IG-7.1.0.war from the ForgeRock BackStage download site.

  4. Copy the IG-7.1.0.war to the JBoss deployment directory:

    $ cp IG-7.1.0.war /path/to/jboss/standalone/deployments/IG-7.1.0.war
  5. Start JBoss as a standalone server:

    $ /path/to/jboss/bin/standalone.sh

    JBoss deploys IG in the root context.

  6. Check that IG is running in one of the following ways: