Untitled | ForgeRock Identity Gateway

Deployment guide

ForgeRock® Identity Platform serves as the basis for our simple and comprehensive Identity and Access Management solution. We help our customers deepen their relationships with their customers, and improve the productivity and connectivity of their employees and partners. For more information about ForgeRock and about the platform, see https://www.forgerock.com.

This document describes how to build an evaluation-only Docker image by using the Dockerfile provided inside IG-7.2.0.zip.

ForgeRock provides no commercial support for production deployments that use ForgeRock’s evaluation-only Docker images. When deploying the ForgeRock Identity Platform using Docker images, you must build and use your own images for production deployments.

This guide is for ForgeRock Identity Platform developers who want an easy-to-use example of containerized deployment, and for Identity Gateway developers who want to configure a production environment for containerized deployment.

For information about deploying ForgeRock Identity Platform by using DevOps techniques, see ForgeOps' Start here.

This guide assumes that you are familiar with the following topics:

IG, to edit the basic configuration and test the changes.
Docker, to build and run and Docker images.

The examples in this guide use some of the following third-party tools:

curl: https://curl.haxx.se
HTTPie: https://httpie.org
jq: https://stedolan.github.io/jq/
keytool: https://docs.oracle.com/en/java/javase/11/tools/keytool.html

Build and run a Docker image

ForgeRock delivers a Dockerfile inside IG-7.2.0.zip, to help you build an evaluation-only, base Docker image for IG. After building and running the Docker image, add a configuration as described in Add configuration to a Docker image.

The Docker image has the following characteristics:

The Docker image runs on Linux and Mac operating systems.
IG binaries are delivered in /opt/ig.
The environment variable $IG_INSTANCE_DIR has the value /var/ig.
A ForgeRock user with username: forgerock and uid: 11111, runs the IG process and owns the configuration files.

Build the base image for IG

Download IG-7.2.0.zip from the ForgeRock BackStage download site, and unzip. The directory /path/to/identity-gateway is created.
Go to /path/to/identity-gateway:
```
$ cd /path/to/identity-gateway
```

With a Docker daemon running, build a base Docker image:

$ docker build . -f docker/Dockerfile -t ig-image

Sending build context to Docker daemon
Step 1/7 : FROM gcr.io/forgerock-io/java-11:latest
latest: Pulling from forgerock-io/java-11
...
Successfully tagged ig-image:latest

Make sure that the Docker image is available:

$ docker image list

REPOSITORY                   TAG        IMAGE ID
ig-image                     latest
gcr.io/forgerock-io/java-11  latest

Run the Docker image

The following steps run the Docker image on port 8080. Make sure that the port is not being used, or use a different port as described in the procedure.

With a Docker daemon running, run the Docker image:
```
$ docker run -p 8080:8080 ig-image
```
IG starts up, and the console displays the message log.
Go to http://localhost:8080 to view the IG welcome page.

Consider using the following options when you run the Docker image:

The default ports 8080:8080 equate to local-machine-port:internal-container-port. IG can run on a different port, but the container must always run on 8080. The following example runs IG on port 8090:
```
$ docker run -p 8090:8080 ig-image
```
The default configuration directory is /var/ig/. The following example sets the configuration directory to $HOME/.openig:
```
$ docker run -p 8080:8080 -v $HOME/.openig:/var/ig/ ig-image
```
Run the image in sh shell, in interactive mode, using the provided Forgerock user:
```
$ docker run -p 8080:8080 -it --user 11111 ig-image sh
```

Stop the Docker image

List the Docker containers that are running:
```
$ docker container ls
```
For a container with the status Up, use the container ID to stop the container:
```
$ docker container stop CONTAINER_ID
```

Add configuration to a Docker image

The following sections describe how to add configuration to your Docker image. Before working through this section, complete the procedures in Build and run a Docker image.

Run an image with a mutable configuration

This section describes how to add a basic route to your local IG configuration folder, and mount the configuration to the Docker container.

If you change your configuration in a way that doesn’t require IG to restart, you see the change in your running Docker image without restarting it or rebuilding it. For information about configuration changes that require restart, see Changing the Configuration and Restarting IG.

Use this procedure to manage configuration externally to the Docker image. For example, use it when you are developing routes.

Add the following route to your local IG configuration as $HOME/.openig/config/routes/hello.json:

{
  "name": "hello",
  "handler": {
    "type": "StaticResponseHandler",
    "config": {
      "status": 200,
      "headers": {
        "Content-Type": [ "text/plain; charset=UTF-8" ]
      },
      "entity": "Hello world!"
    }
  },
  "condition": "${find(request.uri.path, '^/hello')}"
}

The configuration contains a static response handler to return a "Hello world!" statement when the URI of a request finishes with /hello.

Run the Docker image, using the option to mount the local IG configuration directory:
```
$ docker run -p 8080:8080 -v $HOME/.openig:/var/ig/ ig-image
```
Go to http://localhost:8080/hello to access the route in the mounted configuration.

The "Hello world!" statement is displayed.
Edit hello.json to change the "Hello world!" statement, and save the file.

Go again to http://localhost:8080/hello to see that the message changed without changing your Docker image.

Run an image with an immutable configuration

This section describes how to add a basic route to your local IG configuration folder, copy it into a new Docker image, and run that Docker image.

Unlike the previous example, the Docker image is immutable. If you change your configuration locally, the Docker image is not changed.

Use this procedure to manage configuration within the Docker image. For example, use it when you want to deploy the same configuration multiple times.