MidPoint Quick Start Guide

Last modified 18 Apr 2025 08:31 +02:00
Table of Contents

This guide is here to help you get started and deploy midPoint on your local computer using Docker in minutes.

To make the deployment as easy as possible for you, we provide a BASH script you can use to deploy midPoint even if you’re not proficient in using Docker.

To manage the environment for midPoint, the script uses Docker Compose and multiple containers.

The script is built for Linux and it also works on macOS. If you’re on Microsoft Windows, Docker Desktop may be of use to you. However, we don’t have documentation on working with Docker Desktop yet.

If you know your way around Docker or possibly want to use a different deployment method, you can jump right to the MidPoint Installation Guides.

Requirements

Before you proceed further, make sure the following requirements are satisfied on your computer.

Docker

You need to have Docker installed on your computer. Check the documentation on Docker Engine for guides on setting up Docker.

Quick check if you have Docker installed

Type docker --version in your terminal — if you get something like Docker version 27.5.1, build 9f9e405, you’re good. If not, Docker is not in PATH and likely not installed at all.

BASH

BASH is a widely used shell on Linux-based systems. Usually, if you’re on Linux or macOS, no extra step is needed here.

This script is written for the BASH version 3.2 or newer so it works on all modern Linux systems and macOS.

Run bash --version in your Linux or macOS terminal to find out your BASH version.

Internet Connection

During the initial setup, the script needs an Internet connection to pull the required Docker images from the Docker hub. Once everything is set up, you can work with midPoint offline.

Get the Script

Once you confirm you check all the requirements, you can dive right into the deployment.

  1. Before you download the script, create a directory on your computer.
    You’ll use this directory to host the midPoint instance.

  2. Use curl to download the script into the directory:

    curl -O https://raw.githubusercontent.com/Evolveum/midpoint-docker/master/midpoint-quickstart.sh

    • Alternatively, download the script from GitHub using your web browser.

  3. Make the script executable:

    chmod 744 midpoint-quickstart.sh

Usage of the Script

Go to the directory where you saved the quick start script and run the script from there.

The script takes various commands to start, stop, or clean up the midPoint environment. You can also use a couple of parameters to adjust the behavior of the script. More on that in the sections below.

Start MidPoint

To start your midPoint instance, run the script with the start command:

./midpoint-quickstart.sh start

When you run the script, your current working directory must be the one with the script.

You will see the progress of the deployment (objects created, waiting, healthy, exited, etc.). Once midPoint is ready, the access URL with the default username and password appears.

Table 1. Default access information

URL

http://localhost:8080/midpoint/

Username

administrator

Password

<generated>
Sample output of the start command 
$ ./midpoint-quickstart.sh start
Starting the Inicialization process...
Creating the directory "/mnt/repo/midpoint-docker/midpoint_home".
Creating the directory "/mnt/repo/midpoint-docker/midpoint_home/post-initial-objects".
Creating the directory "/mnt/repo/midpoint-docker/midpoint_home/connid-connectors".
Creating the directory "/mnt/repo/midpoint-docker/midpoint_home/lib".
Inicialization done.
[+] Running 5/5
 ✔ Network midpoint-docker_net                  Created                       0.2s
 ✔ Volume "midpoint-docker_midpoint_data"       Created                       0.0s
 ✔ Container midpoint-docker-midpoint_data-1    Started                       0.2s
 ✔ Container midpoint-docker-data_init-1        Exited                       14.3s
 ✔ Container midpoint-docker-midpoint_server-1  Started                      14.5s
MidPoint has started...
To access the WEB GUI go to http://localhost:8080/midpoint/ .
 Username : administrator
 Password : bU0lG9yEr4 (if not changed yet - init Password)

Access Credentials

By default, the script generates an initial username and password during the midPoint environment initialization. You can find these credentials in your terminal after midPoint starts. The password is stored in plain text in the init_pw file (located in the home directory of the instance) to keep it persistent over restarts.

If you want to set the initial password yourself, use the initpw option.

Better yet, you can change the account credentials post-launch in midPoint. This is the recommended approach. Once you change the credentials, the initial username and password are no longer valid.

We strongly recommend changing the password if you’re up to anything more than a localhost test with dummy data.

Keep the password policy in mind when setting up midPoint passwords.

Avoid Using the Same Folder Names For Multiple Instances

The quick start script uses Docker Compose to create and maintain the midPoint containers. Docker uses the name of the directory with the script as a prefix for newly created objects, such as volumes in /var/lib/docker/volumes.

If you run multiple midPoint instances, run the script from directories of different names. Otherwise, you’d likely face objects reused and overwritten unexpectedly.

  • Correct directory names:

    • /tmp/mp_a/

    • /tmp/mp_b/

  • Incorrect directory names:

    • /tmp/a/mp/

    • /tmp/b/mp/

Clean Up the Environment

When you’re done experimenting, it’s best to "turn off" midPoint cleanly and delete its data, so that unneeded files don’t take up your disk space:

./midpoint-quickstart.sh clean

If the environment is running, it will first stop. Afterward, runtime content is removed:

  • Generated logs

  • Connectors in the midPoint home directory

  • Exported data

  • CSV resource files

Sample output of the clean command 
$ ./midpoint-quickstart.sh clean
Starting the Clean up process...
[+] Running 5/5
✔ Container midpoint-docker-midpoint_server-1  Removed                       0.2s
✔ Container midpoint-docker-data_init-1        Removed                       0.0s
✔ Container midpoint-docker-midpoint_data-1    Removed                       0.1s
✔ Volume midpoint-docker_midpoint_data         Removed                       0.0s
✔ Network midpoint-docker_net                  Removed                       0.2s
Removing "/mnt/repo/midpoint-docker/midpoint_home"
Clean up process done.

If you wish to just stop midPoint and continue where you left off later, use the down command instead.

Commands

Here’s a list of all the commands you can use to tell the quick start script what you want to do.

Table 2. Available commands
Command Description

init

Initialize the environment
Check or create the directory structure for the midPoint home if needed.
This is a part of the up and start commands.

clean

Clean the environment
Delete the midPoint home directory structure.

reset

Reset the environment
Delete and re-create the midPoint home directory structure from scratch.
Shortcut to clean and init command.

start

Start the environment
Initialize the environment (if needed) and start it up.

up

Same as start

down

Shutdown the environment
Stop the environment and remove the container objects except volumes and data in the filesystem.

clean-db

Clean the environment
Delete the container environment, including volumes (such as the home volume and database storage).

help

Show help information and available options. Also shown if you supply an unknown command or parameter.

Command Line Options

There are several parameters you can use to customize the behavior of the script.

Every parameter has a predefined default value. You can use the script with the default values just fine. However, if you want to test midPoint on a more advanced level, the customization options may prove useful to you.

Options must be specified before the command. For example:
./midpoint-quickstart.sh -fg start

Basics

Here are the essential customizations you can start with.

Table 3. Descriptions of the most used command line options
Parameter Description Example

-initpw

Specify the initial password for the administrator.
Use only for the first run. To change the existing administrator password, use midPoint administrative user interface (GUI).

-initpw "Abs0lutely Secure Passphrase!"

-subdir

A comma-separated list of directories to be created during the initialization.
This is useful when you need additional directories.

-subdir post-initial-objects,connid-connectors,lib,exports

-port

Specify the HTTP port for the deployment (localhost:<port>/midpoint/).
Useful for multiple parallel deployments to avoid the "port is already allocated" error and distinguish the deployments by port numbers.

-port 8090

-ver

The version of midPoint to use. The tag published in the public registry always contains midPoint version.
Use this attribute to change the required version without the need to specify the whole image name or the complete tag name (including the base OS).

-ver 4.8.5

Password Policy

In case you decide to change the initial password, keep in mind that there is a password policy in place.

When you set a password that doesn’t comply with the policy, the administrator account won’t be created.

That means that you won’t be able to log into midPoint because administrator is the only account in midPoint after initialization. And when the administrator isn’t there, there’s no account to log into. Although there are workarounds for this, the easiest way out is to clean the environment and start (reinitialize) it again with a proper password.

We recommend changing the initial password as soon as possible after the initial setup. The goal is to avoid having your actual password saved unencrypted in logs or configuration files.

Advanced Options

You can use the options below for more advanced scenarios.

Table 4. Available attributes
Attribute Description

-debug

Show more detailed operation log for the troubleshooting purposes.

-fg

Keep the script attached to the terminal, don’t start in the background. Useful to get more insight into the operations of the script.

-base <base_dir>

Use a custom base directory instead of using the script location for the files.
Default: ./

-home <home_dir>

Place the home directory outside the base directory.
Default: /<base>/midpoint-home/

-uid <uid>

User ID for the processes in the container
Default: the currently logged-in user (current session)

-gid <gid>

Group ID for the processes in the container
Default: the currently logged-in user (current session)

-name <img_name>

Docker image name (without a tag)
Used to construct the final Docker image name for the deployment. See also -ver.

-suffix <img_v_suffix>

Docker image version suffix
Used to construct the final Docker image name for the configuration. See also -ver.

-exec <env_exec_cmd>

Shell command to run and control the environment.
Default: docker. If user isn’t in the docker group, sudo docker is used.

-h

Show help information and available options. Also shown if an unknown command or parameter is supplied.

Exit Codes

In case you decide to experiment with the script, there are several exit codes that can help you debug unexpected situations.

Table 5. Exit codes
Exit Code Meaning

0

Normal exit (expected operation)

1

No command has been requested.

2

Can’t create the directory.

3

Can’t remove the directory.

101

Too short path to process (basic security check).

File Paths in Docker Containers

When you learn to work with midPoint, you may want to, for instance, create a resource and import accounts from a CSV file via the CSV connector. To set up the CSV connector, you need to specify the path to the source CSV file.

Docker containers don’t see paths to files the same as your operating system. When you place an hr-export.csv file to /home/myname/md-quickstart/midpoint-home/, you can’t use this path in midPoint.

Discover File Paths in Containers

To find out the path of your hr-export.csv as midPoint sees it:

  1. List your Docker containers:

    docker ps
CONTAINER ID   IMAGE                            COMMAND                 ...
41b8ffa427ff   evolveum/midpoint:4.9.2-alpine   "/opt/midpoint/bin/m…"  ...
98fb6ba2a28f   postgres:16-alpine               "docker-entrypoint.s…"  ...

  2. Copy the ID of the evolveum/midpoint…​ container.

  3. Open the Docker container console.

    docker exec -it 41b8ffa427ff bash

  4. Search for the file by its name:

    find -type f -name hr-export.csv
./opt/midpoint/var/hr-export.csv

    The output of the find command is the path to the file you can use in midPoint.

  5. Exit the container console using the exit command.

Locate the Files on Your Local File System

When using the quick start script, the home directory is located in the directory where the script is.

In Docker deployments that don’t use the quick start script, the situation is a bit less straightforward.

The location of the midPoint home directory depends on your environment. On Linux, it’s most likely under /var/lib/docker/volumes/<base>/_data/resources, where <base> is the name of the directory where you have the docker-compose.yml used for the particular midPoint instance. Bear in mind that /var/lib is most likely owned by root and you can only access it as such (i.e., with sudo).

To find the exact location if you know the file name, you can use the find command to search your whole file system:

sudo find / -type f -name hr-export.csv

You need to run the search as root because you’re searching directories that don’t belong to you.

We recommend you stop the search as soon as it finds your file. Otherwise, the search will eventually spit a lot of errors when it gets to directories that can’t be searched, such as /proc.

Was this page helpful?
YES NO
Thanks for your feedback