Using the container image

This section describes how to work with the Airlock IAM Docker image after completing the setup (see Running IAM with Docker). It covers common configuration use cases for local environments.

The examples use the Docker CLI, so Docker (e.g., Docker Desktop) must be installed and running. As an alternative, equivalent setups can be defined using docker-compose.yml files; example configurations are provided.

Application parameters as environment variables

Application parameters are the parameters used to launch a process running Airlock IAM. They control runtime behavior, configure the IAM modules, etc.

For each IAM instance, a template instance.properties file is created in the instance directory. This file lists all available application parameters, including their descriptions and default values.

To view the available application parameters and their default values, run the following command in the Docker CLI:

 
Terminal box
docker run --rm quay.io/airlock/iam:8.7 default-parameters

In Docker deployments, all application parameters can be overridden using environment variables. This is especially useful for testing and integration scenarios.

Environment variables are derived from the application parameter name, always written in all-caps, where characters such as “-” and “.” are replaced with “_”.

Example:

iam.log.level --> IAM_LOG_LEVEL

The following examples use environment variables to enable only the IAM Adminapp and set the log level to debug.

Docker CLI:

 
Example
docker run --rm \
   --env "IAM_MODULES=adminapp" \
   --env "IAM_LOG_LEVEL=DEBUG" \
   quay.io/airlock/iam:8.7

docker-compose.yml:

 
Example
version: '3.7'
services:
  iam:
    image: quay.io/airlock/iam:8.7    
    environment:
      - "IAM_MODULES=adminapp"
      - "IAM_LOG_LEVEL=DEBUG"
 
Notice

For more information on application parameters, see Application parameters.

Changing the timezone

By default, the IAM container image uses UTC as its timezone.

To change the timezone

  • For Java applications such as IAM: Use the environment variable TZ.
  • (Optional) To align the container’s system timezone (e.g., for shell commands like date): Bind mount /etc/localtime into the container.

Example 1: Using the environment variable TZ

Docker CLI:

 
Terminal box
docker run --rm --env "TZ=Europe/Zurich" quay.io/airlock/iam:8.7

docker-compose.yml:

 
Example
version: '3.7'
services:
  iam:
    image: quay.io/airlock/iam:8.7    
    environment:
      - "TZ=Europe/Zurich"

Example 2: Aligning the container’s system timezone

Docker CLI:

 
Terminal box
docker run --rm -v /etc/localtime:/etc/localtime:ro quay.io/airlock/iam:8.7

docker-compose.yml:

 
Example
version: '3.7'
services:
  iam:
    image: quay.io/airlock/iam:8.7
    volumes:
      - type: bind
        read_only: true
        source: "/etc/localtime"
        target: "/etc/localtime"

Exernal secrets

If your container platform supports secrets management, an opaque secrets file can be mounted directly into the IAM container. This replaces the default JCEKS used for IAM sensitive values (see Storing sensitive configuration values externally with more direct platform integration).

First, create an opaque secrets file according to applicable instructions for Kubernetes, OpenShift or Docker Swarm.

The secrets file can be mounted to any location in the container, e.g., /my-iam-secrets.properties. The path can be configured using the application parameter iam.sensitive-values.config (as environment variable: IAM_SENSITIVE_VALUES_CONFIG).

See also Application parameters.

 
Terminal box
IAM_SENSITIVE_VALUES_CONFIG=/my-iam-secrets.properties

Resource limits and cgroups

In the context of Docker, cgroups (control groups) are used to limit the resources of a container.

In IAM, the JVM is by default configured to use up to 50% of the available container memory for the heap, by the IAM_JAVA_OPTS parameter with a default value of IAM_JAVA_OPTS=-XX:MaxRAMPercentage=50.

 
Notice

The option -XX:MaxRAMPercentage relates the container memory available to the JVM for the heap to the total amount of container memory.

Do not to set the value of -XX:MaxRAMPercentage too high
If the JVM and additional processes running in the container (e.g., docker exec) exceed the container's memory limit, the container may be killed.

Docker CLI

 
Example
docker run --rm --memory 4g --env "IAM_JAVA_OPTS=-XX:MaxRAMPercentage=50" quay.io/airlock/iam:8.7

docker-compose.yml

 
Example
version: '3.7'
services:
  iam:
    image: quay.io/airlock/iam:8.7    
    environment:
      - "IAM_JAVA_OPTS=-XX:MaxRAMPercentage=50"
    deploy: # Only for Docker Swarm
      resources:
        limits:
          memory: "4G"

Note that the -XshowSettings:vm option will log the memory consumption of the JVM. The -XshowSettings:vm option can be added to IAM_JAVA_OPTS. With the option enabled, this additional log output will be generated:

 
Example
VM settings:
    Max. Heap Size (Estimated): 2.00G
    Using VM: OpenJDK 64-Bit Server VM

Storage and volumes

 
Info

The Airlock IAM docker image is designed for containers to be ephemeral. For this reason, we have used “--rm” in the previous examples, which deletes the container storage upon completion.

In order to keep the configuration directory persistent, Docker volumes or bind mounts can be used.

Inside the Docker image, Airlock IAM expects the configuration directory at:

/home/airlock/iam.

For production-use, creating and copying the complete configuration directory during the build-phase is a viable alternative.

 
Info

During integration, bind mounts are more convenient to use because config files can be edited locally.

Read-only root filesystem

With Docker volumes, the container's root filesystem can be made read-only. Read-only filesystems provide improved security through stronger isolation.

The work directory must always be writable. The default work directory is /home/airlock/work, but you can change its path using the application parameter iam.workdir, defined either in the instance.configuration file or as an environment variable.

Typically, the config root directory /home/airlock/iam should also be writable, otherwise some functions such as activating a configuration through the Config Editor will not be available.

For the work directory ephemeral “tmpfs” mounts can be used since its contents are always re-created during start-up:

Docker CLI

 
Example
docker run --rm --read-only --mount type=volume,target=/home/airlock/iam --mount type=tmpfs,target=/home/airlock/work quay.io/airlock/iam:8.7

docker-compose.yml

 
Example
version: '3.7'
services:
  iam:
    image: quay.io/airlock/iam:8.7    
    read_only: true
    volumes:
      - type: volume
        target: "/home/airlock/iam"
      - type: tmpfs
        target: "/home/airlock/work"
 
Info

You may also use “type=volume” instead of “type=tmpfs” to create an anonymous volume. See https://docs.docker.com/storage/ for a complete overview of all Docker storage options and how they differ.

Separate containers for Loginapp and Adminapp

For security reasons we recommend running external web application modules like the Loginapp, and internal web applications, like the Adminapp and the Service Container, in separate Docker containers.

You can achieve this by setting the environment variable --env “IAM_MODULES” to loginapp or adminapp,service-container, respectively.

For more information, see Sandboxing with profiles and the following modules.

Logging

You may want to only log to stdout. To disable log output to files inside the configuration directory, disable the respective appenders for each web application in the log4j/all-modules.xml file. See Logging configuration.

Execute IAM CLI commands without a running container

If you do not want to install IAM locally or do not have an IAM container running, you can still execute IAM CLI commands on any machine with Docker installed.

To do so, run the following command using the Docker CLI:

 
Example
docker run --rm -it --entrypoint /bin/bash -v "$(pwd)/iam:/home/airlock/iam" quay.io/airlock/iam:8.7