Introduction

Here we describe Docker images for midPoint that are to be used within the TIER IdM environment.

The images can be found in the TIER/midPoint_container GitHub project in the midpoint directory. (Besides that, the project contains a demonstration of the use of these containers in a wider environment consisting of Grouper, Shibboleth, LDAP directory, RabbitMQ messaging, and sample source and target systems.)

Getting started

The easiest way how to start dockerized midPoint is to use provided docker-compose.yml file. There are the following two options.

Using existing images

TODO this does not work yet

$ git clone https://github.internet2.edu/TIER/midPoint_container.git
$ cd midPoint_container/midpoint
$ docker-compose up --no-build

Building your own images

$ git clone https://github.internet2.edu/TIER/midPoint_container.git
$ cd midPoint_container/midpoint
$ ./download-midpoint
$ docker-compose up --build

After docker-compose up command successfully finishes you should see something like this on the console:

midpoint-server_1  | midpoint;midpoint.log;demo;3.9-SNAPSHOT;2018-09-20 16:25:22,191 [] [main] INFO (org.springframework.boot.web.embedded.tomcat.TomcatWebServer): Tomcat started on port(s): 8080 (http) 9090 (http) with context path '/midpoint'
midpoint-server_1  | midpoint;midpoint.log;demo;3.9-SNAPSHOT;2018-09-20 16:25:22,209 [] [main] INFO (com.evolveum.midpoint.web.boot.MidPointSpringApplication): Started MidPointSpringApplication in 60.512 seconds (JVM running for 61.688)

Now you can log into midPoint using https://localhost:8443/midpoint URL, with an user of administrator and a password of 5ecr3t. For Shibboleth authentication demonstration, please visit Shibboleth authentication demonstration section below.

Containers

The default composition contains two containers:

You can either use these two containers together, or you can replace midpoint-data with your own Docker container, or even external repository implementation - either on-premises or in cloud. See Alternative repository demonstration section below for more information.

Communication

By default, containers publish the following TCP ports. (Port mapped to localhost denotes the mapping of container port to the host port where it can be reached from the outside.)

Docker volumes

The following volumes are created to persist data and other relevant files.

Configuring the containers

These containers are configured by the following means.

Environment variables

Some parameters are configured by setting environment variables. For example:

$ export ENV="test" USERTOKEN="3.9" MEM="4096m"
$ docker-compose up

Or like this:

$ env ENV="test" USERTOKEN="3.9" MEM="4096m" docker-compose up

Docker secrets and configs

Secrets and configs are stored in the configs-and-secrets directory. They are provided to midPoint containers in appropriate ways. (Currently, secrets are passed as Docker secrets, configs are mounted as volumes. This might be changed in the future.) For detailed information on individual items please see the following sections.

Configuring specific midPoint features

In this section we describe how to configure and use specific features of this midPoint dockerization.

Logging

Logging is configured by setting the following environment variables:

According to the specification, semicolons and spaces in these fields are eliminated (replaced by underscores).

Repository

Repository configuration is done via the following environment variables.

Besides that, the following Docker secrets are used:

Authentication

This midPoint dockerization supports two authentication mechanisms.

Authentication configuration is done using the following environment variables.

Besides variables, the following secrets and configs are used for Shibboleth-based authentication.

Other

Other aspects can be configured using the following variables and Docker secrets or configs.

Other configs/secrets are:

Shibboleth authentication demonstration

In order to quickly verify the Shibboleth integration feature of the standard midPoint container we have provided a sample Shibboleth composition in demo/shibboleth directory. It contains a Shibboleth IdP container (idp) and an LDAP directory container (directory). They are to be started independently on midPoint.

Here we show how:

Starting Shibboleth containers

$ cd demo/shibboleth
$ docker-compose up

Starting midPoint containers

$ cd midpoint
$ env AUTHENTICATION=shibboleth docker-compose up

Logging in

Use https://localhost:8443/midpoint URL as before. This time you will be redirected to Shibboleth login screen where you enter username of administrator and a password of password.

These values are checked against LDAP directory. Then the uid of administrator is passed to midPoint as authenticated user's login name.

Alternative repository demonstration

In order to quickly verify the ability to configure alternative repository location we have provided a sample PostgreSQL container in demo/postgresql directory. There are two ways how to invoke it:

1. PostgreSQL can be started as part of the midPoint composition.
2. PostgreSQL can be started independently of the midPoint composition.

Starting PostgreSQL as part of the midPoint composition

$ cd midpoint
$ docker-compose -f docker-compose.yml -f ../demo/postgresql/midpoint-additions.yml up midpoint-server postgresql

The midpoint-additions.yml composition file looks like this:

services:
  postgresql:
    build: ../demo/postgresql/postgresql/
    environment:
     - POSTGRES_PASSWORD=password
    expose:
     - 5432
    ports:
     - 5432:5432
    networks:
     - back
    volumes:
     - postgresql_data:/var/lib/postgresql/data

  midpoint-server:
    environment:
     - REPO_DATABASE_TYPE=postgresql
     - REPO_HOST=postgresql
     - REPO_DATABASE=midpoint
     - REPO_USER=midpoint

volumes:
  postgresql_data:

Notes:

1. The first service declaration (posgresql) creates a container hosting the new repository.
2. The second service declaration (midpoint-server) adds a couple of environment variables needed to tell midPoint how to access the new repository.

You can safely ignore console messages like this:

postgresql_1       | ERROR:  could not serialize access due to read/write dependencies among transactions
postgresql_1       | DETAIL:  Reason code: Canceled on identification as a pivot, during write.
postgresql_1       | HINT:  The transaction might succeed if retried.

This is a part of standard midPoint conflict resolution process. The mentioned transactions are really retried and they succeed eventually.

Starting PostgreSQL independently of the midPoint composition

$ cd demo/postgresql
$ docker-compose up

and

$ cd midpoint
$ docker-compose -f docker-compose.yml -f ../demo/postgresql/midpoint-additions-for-standalone-run.yml up midpoint-server

Here the additional compose file looks like this:

services:
  midpoint-server:
    environment:
     - REPO_DATABASE_TYPE=postgresql
     - REPO_HOST=postgresql
     - REPO_DATABASE=midpoint
     - REPO_USER=midpoint
    networks:
     - postgresql_net

networks:
  postgresql_net:
    external: true

We need this file mainly to allow midpoint-server container to directly communicate with the postgresql host (via postgresql_net network). Setting of the environment variables could be done also from the command line, as will be seen in the following example.

Note that the PostgreSQL database will be different from the database created in the first case. The first one resides in midpoint_postgresql_data volume, this one in postgresql_data volume.

Using an externally provided repository

Here we show how to use externally provided repository. We have chosen Oracle as an example; mainly because it requires adding custom drivers to midPoint.

The custom drivers reside in lib subdirectory of midPoint home directory. The home directory is available as a Docker volume with a default name of midpoint_midpoint_home (assuming midPoint was started at least once). So, after downloading the Oracle driver you can copy it into the appropriate place using e.g. for following command:

$ sudo cp ~/Downloads/ojdbc7.jar /var/lib/docker/volumes/midpoint_midpoint_home/_data/lib

Let us assume that our server is available on host 192.168.56.101. We can then tell midPoint to connect to the Oracle database using the following command. (Do not forget to set the correct password in configs-and-secrets/midpoint/application/database_password.txt as shown below.)

$ cd midpoint
$ echo oracle > configs-and-secrets/midpoint/application/database_password.txt
$ env REPO_DATABASE_TYPE=oracle REPO_HOST=192.168.56.101 REPO_USER=system docker-compose up midpoint-server

After successful start of midPoint you can login and check that the database is really an Oracle one.