Docker Compose

Last modified 10 Jan 2025 08:23 +01:00

This page is related to the containerized midPoint documentation. There will be dedicated samples related to the Docker Compose. The content can also be used out of the Docker environment, but a small syntax update may be needed.

You may also be interested in :

  • Common containers related information with possibilities for customization of the installation

  • Kubernetes related information with sample configuration

  • Container customization related information

Preparing the Environment

To have a working midPoint environment, more than just one application is needed. To address this complexity, we prepared a description file, which can be easily processed - a Docker Compose file. This file contains the definition for all parts and also provides the necessary settings. The benefit for the user is that it can be "simply run", and the isolated working environment is available for you.

Docker Engine

For the Docker Compose, the Docker environment is required. The requirement for this environment is the availability of the Docker Engine.

Docker documentation related to installation based on OS:

  • Linux - Docker Engine
    The Docker Engine can be installed directly.

  • Windows - Docker Desktop
    For Windows, the Docker Engine is only available as a part of the Docker Desktop application. Any configuration of Docker Desktop installation is suitable for our purpose. Feel free to follow the default setting during the installation process.

Docker Compose Definition

Download the Docker Compose file. You can use your preferred browser using the link to GitHub, or you can use the following curl command.

curl -O https://raw.githubusercontent.com/Evolveum/midpoint-docker/master/docker-compose.yml

Once this file is stored in the file with the "default" name docker-compose.yml, the usage is easier. In case a different name is used, the filename has to be defined explicitly in all Docker Compose commands with the parameter -f.

All objects based on the Docker Compose file will contain the directory’s name as a prefix.

Database Password Initialization (Optional)

You can find a "static" password for the database in the Docker Compose definition - db.secret.pw.007 . This configuration is less secure (known password), but the focus is on "quick start" - simplicity.

If you want to manage passwords more securely, you can look at the Secrets in Compose page.

To use secrets in Docker Compose, you must append the _FILE suffix to all environment variables that store passwords.

Namely, rename:

  • POSTGRES_PASSWORD to POSTGRES_PASSWORD_FILE

  • MP_SET_midpoint_repository_jdbcPassword to MP_SET_midpoint_repository_jdbcPassword_FILE (two occurrences)

This is because the value of each variable will be the path to a file containing the secret instead of the secret itself as a plain string. Any image used in the provided Docker Compose file can work with this suffix.

Managing the Environment

start the environment in the background
docker compose up -d

It will take some time to start. For a few seconds, the web GUI will not be available - it is expected. There is an initiation in progress - starting, loading initial objects into the empty repository, etc.

If you want to stop the container, use the following command.

stop the environment
docker compose down

This command will stop the container but keep it defined. The data stays available for the next run.

To reset the environment (clean up the data), you can use the following command:

stop the midPoint environment and clean up the relevant data
docker compose down -v

Using the -v parameter also causes removing the volumes. Volumes are the space where the data is stored out of the container - persistent storage over the container remove/re-create.

In other words, user data related to the container will also be removed, e.g., the DB’s (repository) content.

To sum up, below is a table with the most often-used commands.

Table 1. A summary of the available Docker Compose commands.
Command Result

docker compose up -d

Start the environment based on the Docker Compose file content

docker compose down

Stop the environment (the stored data is kept)

docker compose down -v

Stop the environment and clean up the relevant data

docker ps -a

List all containers currently used in the system

In case you have installed the Docker Desktop, additionally you also have a GUI available to start and stop the environment. However, there is no additional feature compared to the command line usage.

The services from the Docker Compose file are grouped. The name of the group is the name of the directory where the Docker Compose file is located.

After the first docker compose up command, the environment is available in the list. There are buttons on the related row in the list with allowed actions: start/stop and remove.

dockerDesktop
Figure 1. Docker Desktop with the midPoint environment

MidPoint User Interface

MidPoint has a web administration user interface. This is a primary user interface for using and configuring midPoint. By default, the user interface is accessible at port 8080:

http://localhost:8080/midpoint/

Logging In

Please log in to user interface as an administrator user.

Username

administrator

Password

Test5ecr3t

For security reasons, there is no default password. With the first run, an administrator user is initiated. If the required password is not set, a generated one is there.

The password Test5ecr3t is set by the configuration in the provided Docker Compose file.

For more information, see Administrator Initial Password doc page.

In the releases before 4.8.1 (up to 4.8), the default password was 5ecr3t. If you are running one of these versions, here are the default credentials.

Username

administrator

Password

5ecr3t

Take A Look Around

The administrator is an all-powerful user. Therefore, all the capabilities of midPoint are at your disposal. Feel free to take a look around. Some places of the user interface may be confusing, but you certainly find some familiar places as well.

  • The Self Service part of the interface is used to manage the identity and privileges of a user who is currently logged in.

  • The Administration part of the user interface is used to manage user identities, roles, organizational structure, and policies. This part is used for routine administration of the system. At this stage, this is perhaps the most interesting part of midPoint to explore.

  • The Configuration part of the user interface is used to customize midPoint behavior, going deep into the midPoint internals.

midpoint gui

Terminology

MidPoint uses terms that are quite common in the identity management field. However, it may be slightly confusing for people coming from other fields. The following list explains basic midPoint terms:

  • User means user record (profile) in the midPoint database. This data record usually contains unified data synchronized from source systems.

  • Resource is a remote system that is connected to midPoint. It may be a source system that feeds data to midPoint. Or it may be a target system managed by midPoint.

  • Account is a data structure (user profile) that resides on resource (source or target system). MidPoint reads data from accounts or manages the accounts.

  • Role gives privileges to users. It may also specify what accounts a user should have on what resources .

Next Steps

MidPoint will not do much on its own. We need to connect midPoint to a source or target system (a resource) to see it shine. However, midPoint is a very powerful and comprehensive system. There are many things that can be set up, customized, and adjusted when a new resource is connected to midPoint. The configuration may be somehow overwhelming for a new midPoint engineer.

It will take some time to understand how midPoint works. However, any time invested in learning midPoint will be paid back many times over.

There are three great ways how to start learning about midPoint:

First Steps Methodology Webinar Video

  • Video tutorials on Evolveum YouTube channel. There is a series of tutorials based on the book. There are also videos explaining various details of midPoint configuration and deployment.

  • MidPoint Book provides a general introduction to identity management. It explains how midPoint works, and provides examples, ideas, and tips for the midPoint configuration, deployment, and use. This is the book to learn about midPoint. It is freely available for online reading and downloading.

  • Trainings organized by Evolveum. These are usually remote, instructor-led trainings designed by the midPoint authors.

There are also additional sources of information that are usually suitable for engineers with some experience:

  • docs.evolveum.com: This entire site is dedicated to documentation. It is more than worth exploring the content.

  • MidPoint mailing lists are a great place to discuss midPoint.

  • Conference talks and workshop recordings are good resources for people who like to sit back and listen.

Frequently Asked Questions

MidPoint won’t start

Q: MidPoint won’t start, I cannot access the 8080 port.

A: MidPoint is a substantial software system. It usually takes 1-2 minutes for midPoint to start up based on hardware. You can monitor the progress of midPoint startup by looking into the midPoint logs.

Something went wrong …​

Q: Something went wrong. I have no idea what is going on.

A: The best way to start midPoint diagnostics is to look into the midPoint logs.

The logs are visible in the console or the standard docker logging mechanism: docker logs midpoint_server.

My first resource won’t work

Q: My first resource won’t work. There are connection errors. I can see no data. Nothing works.

A: Have a look at the error message. You can expand the error message to get more details about the problem. However, please keep in mind that connecting a new system to midPoint may be tricky. There are nice systems that use standard protocols and provide good error messages. However, many systems are not very nice. They deviate from standards, require exotic configurations, and return cryptic error messages. If the resource does not work on the first try, it is usually helpful to learn more about midPoint and its workings.

Something else

Please check out MidPoint FAQs.

Was this page helpful?
YES NO
Thanks for your feedback