Docker Compose

Last modified 27 Jun 2025 10:39 +02:00

Table of Contents

Preparing the Environment
Managing the Environment
MidPoint User Interface
- Logging In
- Take a Look Around
Terminology
Next Steps
Frequently Asked Questions

This page describes midPoint installation in Docker and includes Docker Compose samples.

You can use the Docker environment provided by midPoint out-of-box, however, small syntax updates may be required.

For broader context, see :

Common containers related information with options to customize the installation.
Kubernetes related information with a 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 a definition for all parts and also provides the necessary settings. You can "run" the file and thus create an isolated working environment.

Docker Engine

To install midPoint, you will need Docker Compose which requires a Docker environment. The environment must include the Docker Engine.

See Docker documentation related to installation based on your 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 the Docker Desktop installation is suitable for the purposes of this guide. Feel free to use the default settings during the installation process.

Docker Compose Definition

Download the Docker Compose file from Github. In your terminal, you can download it by running the following curl command:

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

It is recommended not to rename the downloaded docker-compose.yml file. If you use a different name, you need to define it explicitly in all Docker Compose commands with the -f parameter.

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

Database Password Initialization (Optional)

You can find a "static" password for the database in the Docker Compose definition file, db.secret.pw.007. This configuration is less secure, but the focus is on deploying quickly in this case.

If you want to manage passwords more securely, refer to Secrets in Compose.

To use secrets in Docker Compose, you need to 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

The basic management commands are used to:

Start the environment in the background:
```
docker compose up -d
```
The web GUI becomes available once the environment starts and the initiation (loading initial objects into the empty repository, etc.) is completed. This may take some time.
Stop the environment:
```
docker compose down
```
This command stops the container but keeps it defined. The data stays available for the next run.

Stop and reset the environment (clean up the data):

docker compose down -v

Using the -v parameter also removes the volumes. Volumes are spaces where data is stored outside of containers, i.e. a persistent storage that holds data so that it can be re-used after removing or re-creating containers.

In other words, if you use the -v parameter, user data related to the container will also be removed, for example the DB (repository) content.

The following table shows the most common commands:

Table 1. A summary of the available Docker Compose commands.
Command	Result
`docker compose up -d`	Starts the environment based on the Docker Compose file content.
`docker compose down`	Stops the environment (the stored data is kept).
`docker compose down -v`	Stops the environment and cleans up the relevant data.
`docker ps -a`	Lists all containers currently used in the system.

If you have installed Docker Desktop, you can also start/stop the environment in GUI.

The services defined in 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 running the first docker compose up command, the environment is shown in the list of available environments. You can start/stop/remove the environment using the buttons for the respective environment.

Figure 1. Docker Desktop with the midPoint environment

MidPoint User Interface

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

http://localhost:8080/midpoint/

Logging In

In midPoint 4.8.1 and newer versions, there is no default password for security reasons. With the first run, an administrator user is initialized and a new password is generated. This is then saved in a log file. See Administrator Initial Password for details.
In midPoint 4.8 and lower versions, the default credentials are as follows:

Username

administrator

Password

5ecr3t

Username	`administrator`
Password	`5ecr3t`

Take a Look Around

The administrator is an all-powerful user. Therefore, all capabilities of midPoint are at your disposal.

The Self Service part of the interface is used to manage the identity and privileges of the currently logged in user.
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.

Terminology

MidPoint uses terminology that is common in the identity management field. The following list explains some of the elementary midPoint terms:

User means a user record (profile) in the midPoint database. This data record usually contains unified data synchronized with source systems.
Resource is a remote system that is connected to midPoint. It can be a source system that feeds data to midPoint, or a target system managed by midPoint.
Account is a data structure (user profile) that resides on a resource (source or target system). MidPoint reads data from accounts and manages them.
Role gives privileges to users. It may also specify what accounts a user should have in specific resources.

Next Steps

MidPoint alone will not do much. You need to connect midPoint to a source or target system (a resource). 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.

There are some great ways to start learning about midPoint:

First Steps methodology. These are also covered by the First Steps Methodology Webinar video that includes a live demonstration.

First Steps Methodology Webinar Video

Video tutorials on the Evolveum YouTube channel. There is a series of tutorials based on MidPoint Book, together with 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 substantially complex software system. Depending on your hardware, it can take 1-2 minutes for midPoint to start up. You can monitor the progress of midPoint starting up 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 a midPoint diagnostic is to look into the midPoint logs.

The logs are visible in the console through 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: Examine the error message. You can expand the error message to get more details. 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.