Downloading, starting, and stopping 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

Download the IG .zip file

The .zip file unpacks into a /path/to/identity-gateway directory with the following content:

bin: Start and stop executables
classes: Initially empty; used to install patches from ForgeRock support
docker/Dockerfile: Dockerfile and README to build an IG Docker image
legal-notices: Licenses and copyrights
lib: IG and third-party libraries

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

The installation directory should be a new, empty directory. Installing IG into an existing installation directory can cause errors.
Download IG-2023.9.0.zip from the ForgeRock BackStage download site, and copy the .zip file to the installation directory:
```
$ cp IG-2023.9.0.zip /path/to/IG-2023.9.0.zip
```
Unzip the file:
```
$ unzip IG-2023.9.0.zip
```
The directory /path/to/identity-gateway is created.

Start IG

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.

Start IG:
- Linux
- Windows
$ /path/to/identity-gateway/bin/start.sh ... ... started in 1234ms on ports : [8080 8443]
C:\path\to\identity-gateway\bin\start.bat
By default, IG configuration files are located under $HOME/.openig (on Windows appdata\OpenIG). For information about how to use a different location, refer to Change the base location of the IG configuration.
Check that IG is running in one of the following ways:
- Ping IG at http://ig.example.com:8080/openig/ping, and make sure an HTTP 200 is returned.
- Access the IG welcome page at http://ig.example.com:8080.
- When IG is running in development mode, display the product version and build information at http://ig.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, refer to AdminHttpApplication (admin.json).

Allow startup when there is an existing PID file

By default, if there is an existing PID file during startup the startup fails. Use one of the following ways to allow startup when there is an existing PID file. IG then removes the existing PID file and creates a new one during startup.

Add the following configuration to admin.json and restart IG:
```
{
  "pidFileMode": "override"
}
```

Define an environment variable for the configuration token ig.pid.file.mode, and then start IG in the same terminal:

Linux
Windows

$ IG_PID_FILE_MODE=override /path/to/identity-gateway/bin/start.sh

C:\IG_PID_FILE_MODE=override
C:\path\to\identity-gateway\bin\start.bat appdata\OpenIG

Define a system property for the configuration token ig.pid.file.mode when you start IG:
- Linux
- Windows
$HOME/.openig/env.sh
appdata\OpenIG\env.sh
```
export "IG_OPTS=-Dig.pid.file.mode=override"
```

Stop IG

Use the stop.sh script to stop an instance of IG, specifying the instance directory as an argument. If the instance directory is not specified, IG uses the default instance directory:

Linux
Windows

$ /path/to/identity-gateway/bin/stop.sh $HOME/.openig

C:\path\to\identity-gateway\bin\stop.bat appdata\OpenIG

IG 2023.9