Warning |
---|
This is a work in progress. When using it we recommend to use the latest stable version 1.1 (see "Getting started" section below). |
Table of Contents |
---|
Introduction
Here we describe Docker image for midPoint that is to be used within the TIER IdM environment.
The image can be found in the TIER/midPoint_container GitHub project.
Besides the image itself, the project contains a couple of demonstrations of its usage:
...
live document. If you encounter issues, please let us know via the |
Table of Contents |
---|
Introduction
This page shows how to get started with a Docker image for the midPoint component of the InCommon Trusted Access Platform.
Anchor | ||||
---|---|---|---|---|
|
In order to set up and run this container and associated demonstrations, you need a Linux machine with a reasonably recent Docker and docker-compose
installation. The most advanced demo/complexgrouper
optionally uses an LDAP browser, e.g. Apache Directory Studio that itself requires Java.
...
- Docker 18.06.1-ce,
- docker-compose 1.17.1 (and 1.22.0),
- libxml2-utils package (in order to have
xmllint
command available), - Apache Directory Studio 2.0.0.v20170904-M13 with OpenJDK 8.
...
Also, make sure appropriate ports are available on the host machine. They are listed in the documentation to individual demonstrations; usually they are 8443 and 3306, sometimes 389, 4443443, or 5432. The demo/complexgrouper
needs even more free ports, please see the description.
Getting started (simple demo)
The image cannot be "run" by itself as it requires a midPoint repository - i.e. an SQL database - to execute. So the easiest way how to start dockerized midPoint is to use one of the provided demonstrations. The most logical choice for the first run just getting started with midPoint is demo/simple
.
Code Block | ||
---|---|---|
| ||
$ git clone --branch v1.1 https://github.internet2.edu/TIERDocker/midPoint_container.git $ cd midPoint_container/demo/simple $ docker-compose up |
Building own images
The above commands download tier/TAP midpoint
image from the Docker hubInternet2's enterprise github. Alternatively, you can build this image yourself. Here is how:
Code Block | ||
---|---|---|
| ||
$ git clone --branch v1.1 https://github.internet2.edu/TIERDocker/midPoint_container.git $ cd midPoint_container $ ./build.sh $ cd demo/simple $ docker-compose up |
(Note the build.sh
has a -n
switch that skips downloading the midPoint distribution archive, saving some time during repeated builds.)
After starting
After docker-compose up
command successfully finishes you should see something like this on the console:
...
Now you can log into midPoint using https://localhost:8443/midpoint URL, with an user of administrator
and a password of 5ecr3t
. If you are using midPoint 4.8.1 or greater please check the documentation on how to set an initial password.
Beyond the simple demo
Besides the midPoint image itself, and the simple demo discussed above, the project contains demonstrations that integrate midPoint with selected other components
Demonstration Instruction Pages | Description |
---|---|
demo/simple | The simplest use of midPoint: just running it along with a dockerized MariaDB repository. |
demo/shibboleth | Shows how to use midPoint with the Shibboleth authentication. |
demo/postgresql | Demonstration of how to use an alternative repository (PostgreSQL running in a Docker container) instead of MariaDB-based one. |
demo/extrepo | Demonstration of how to use externally hosted repository instead of MariaDB-based one. It also shows database schema version mismatch detection as well as automated upgrade procedure. |
demo/grouper | This is a demonstration of the use of midPoint image in a wider environment consisting of Grouper, Shibboleth, LDAP directory, RabbitMQ messaging, and sample source and target systems. For a step-by-step walk-through, see the Grouper Integration Demo page. |
Configuring the container (general information)
The lowest level of configuration of the midPoint container is during its inclusion into a Docker composition. There is the full set of environment properties and other configurable items (e.g. Docker secrets and configs) available.
During the composition some of the environment properties can be made accessible from the outside. This depends strictly on the compositor. The demonstrations here show some of the options.
How to set environment variables after composition is done
After the composition is done, you can set the environment variables like this:
Code Block | ||
---|---|---|
| ||
$ export ENV="test" USERTOKEN="34.0.91" MP_MEM="4096m" $ docker-compose up |
...
Code Block | ||
---|---|---|
| ||
$ env ENV="test" USERTOKEN="34.0.91" MP_MEM="4096m" docker-compose up |
How to set Docker secrets and configs
The way of accessing secrets and configs is specific to the composition. In our demonstrations these 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 container features
In this section we describe how to configure and use specific features of this midPoint dockerization.
Repository
Repository configuration is done via the following environment variables.
Environment variable | Meaning | Default value |
---|---|---|
REPO_DATABASE_TYPE | Type of the database. Supported values are mariadb , mysql , postgresql , sqlserver , oracle . It is possible to use H2 as well but H2 is inappropriate for production use. | mariadb |
REPO_JDBC_URL | URL of the database. | MariaDB: MySQL: PostgreSQL: SQL Server: Oracle: |
REPO_HOST | Host of the database. Used to construct the URL. | midpoint_data |
REPO_PORT | Port of the database. Used to construct the URL. | 3306, 5432, 1433, 1521 for MariaDB/MySQL, PostgreSQL, SQL Server and Oracle, respectively |
REPO_DATABASE | Specific database to connect to. Used to construct the URL. | registry |
REPO_USER | User under which the connection to the database is made. | registry_user |
REPO_PASSWORD_FILE | File (e.g. holding a docker secret) that contains the password for the db connection. | /run/secrets/mp_database_password.txt |
REPO_MISSING_SCHEMA_ACTION | What should midPoint do if the database schema is missing (options: warn , stop , create ). | create |
REPO_UPGRADEABLE_SCHEMA_ACTION | What should midPoint do if the database schema is obsolete but upgradeable (options: warn , stop , upgrade ). As of midPoint 34.90, the only automated transition available is from 3.8 to 3.9. | stop |
REPO_SCHEMA_VERSION_IF_MISSING | For midPoint versions before 3.9 that do not have schema information explicitly stored in the database, this parameter allows specifying the version externally. It can be used for automated upgrade from 3.8 to 3.9. (In such cases, specify it to be 3.8, assuming this is your schema version.) | |
REPO_SCHEMA_VARIANT | Used to specify what schema variant is to be used for automated creation or upgrade of the database schema. Currently the only known variant is Beware: it is the administrator's responsibility to choose the correct variant! Currently midPoint does not try to determine the variant present in the database. So be sure to avoid applying e.g. |
...
Of course, you can provide the password file in any other way, assuming you correctly set REPO_PASSWORD_FILE
environment variable.
Logging
Logging is configured by setting the following environment variables:
...
According to the specification, semicolons and spaces in these fields are eliminated. We decided to replace them by underscores.
Authentication
This midPoint dockerization supports two authentication mechanisms.
...
Secret | Description | Typical location in demonstration scenarios |
---|---|---|
mp_sp-key.pem | Service provider private key | configs-and-secrets/midpoint/shibboleth/sp-key.pem |
Other
Other aspects can be configured using the following variables and Docker secrets or configs.
...
Item | Kind | Meaning | Location |
---|---|---|---|
mp_host-key.pem | secret | Private key for Apache httpd | configs-and-secrets/midpoint/httpd/host-key.pem |
mp_keystore_password.txt | secret | Java keystore password used by midPoint e.g. to encrypt sensitive information stored in the repository. | configs-and-secrets/midpoint/application/keystore_password.txt |