MidPoint Quick Start Guide - quickstart script

Last modified 10 Jan 2025 08:23 +01:00
Table of Contents

This page is meant for users without more profound knowledge of the container environment. It describes the start script, which should help users start the midPoint environment with the easily reachable home file system.

In case your knowledge is on an advanced level, feel free to follow other pages like:

Requirements

Even though we are trying to make it as easy as possible, there are several requirements that have to be met. These requirements can be checked in advance, e.g., by IT support.

Working Docker Environment

The script helps with starting parameters, but a working environment is simply needed.
The docker execution file should be located in PATH - once you write "simply" the docker command, the system should know where to find it.

Docker documentation related to the environment preparation can be found at Docker Hub.

Bash

This is a widely available Shell on Linux-based systems. Usually, no extra step is needed.
The script is written for the version which would provide compatibility on both Linux and MacOS systems.

To address as wide compatibility level as possible the BASH version 3.2 has been used. The newer version is not an issue.

Start Script

Start script midpoint-quickstart.sh is available in the midpoint-docker git repository.
The script can be located anywhere, but the location of the script sets the default where the newly created directories/files will be located.

To download it, you can use the curl command or your preferred browser using the link to GitHub.

Get available start script definition (@github)
curl -O https://raw.githubusercontent.com/Evolveum/midpoint-docker/master/midpoint-quickstart.sh

Internet Connection

Once everything is prepared and cached (e.g., run for the first time), the internet is not needed for the run itself. Unfortunately, the files have to reach your computer, so the internet is needed for the first initial phase.

Usage of the script

The script is prepared to be customizable by the parameters. To run it, you should be in the same directory as the file is located.

generic format for the script run
./midpoint-quickstart.sh [options] [command]

Behind the script, Docker Compose is utilized, using the directory name as a prefix for newly created objects. In case you have more instances, the last part of the path (directory name) should differ. The different path with the same "last" directory name would cause reusing/overwriting the objects.

  • Incorrect names

    • /tmp/a/mp

    • /tmp/b/mp

  • Correct names

    • /tmp/mp_a

    • /tmp/mp_b

Quick start

Later, all options will be mentioned. At this point, the "basic" commands are listed.

Command Result

./midpoint-quickstart.sh up

Start the environment

./midpoint-quickstart.sh down

Stop the environment (keeping repository)

./midpoint-quickstart.sh clean-db

Stop the environment (removing repository)

./midpoint-quickstart.sh clean

Clean up the environment

Start environment

Starting environment
./midpoint-quickstart.sh up

Some technical information will temporarily end with "Waiting to midPoint start up…​" message. Once midPoint fully starts, the information related to the URL and default username and password3) will appear.

Table 1. Access information in case of default values

URL

http://localhost:8080/midpoint/

Username

administrator

Password

Test5ecr3t 3)
Sample output of the start command 
$ ./midpoint-quickstart.sh up
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
Waiting to midPoint start up...
MidPoint has started...
To access the WEB GUI go to http://localhost:8080/midpoint/ .
 Username : administrator
 Password : Test5ecr3t (if not changed yet - init Password)

3) By default, the password is generated and has to be found in the log. To make the start easy for you, we have preset an initial password. You have the option to set your own. In case you don’t overwrite the parameter, the script offers the password Test5ecr3t.

Once you change the password in the application (it is more than recommended), the initial password will no longer be valid.

Clean up the environment

Clean up the environment
./midpoint-quickstart.sh clean

If the environment is running, it will first stop. Afterward, previously generated directories (the whole content) will be removed.

It includes (for example):

  • generated logs

  • connectors in the "live" midPoint home directory

  • exported data

  • CSV resource file(s)

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.

Customization

There are several possible parameters and commands that can impact the resulting state.

Commands

The most often used commands will probably be up and clean. The following table shows the possible commands.

Table 2. Available commands
Command Description

init

Initialize the environment
Check and create the directory structure for the midPoint home if needed
It is part of "up/start" command.

clean

Clean the environment
Delete directory structure for the midPoint home

reset

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

up / start

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

down

Shutdown the environment
Stop the environment and remove the container objects except volumes and data on the "external" filesystem.

clean-db

Remove the container environment, volumes included.
Clean the environment - containers, volumes (db storage), etc.

help

Show the help (this information)

Attributes

There is a set of default values predefined in the script. With the default values, the application will run fine. As this script would be primarily a helper for you, there is an option to change it so you can customize it for your needs.

Let’s focus on the "first steps" with midPoint. In that case, the "interesting" attributes are :

  • initpw
    This parameter can be used to create the initial password for the administrator user object.

Password Policy

Once you decide to set up your initial password, please keep in mind that there is a password policy in place. If you set a password that does not correspond, the administrator user object will not be imported.

It will not be possible to log into the system because the administrator is the only user in midPoint after the first start of the system.

There is a "workaround" to how the user can be imported. Anyway, the easiest way how to address the situation is to clean the environment and start (reinitialize) a new one with the "proper" password.

Even if you kept the "offered" password, it is recommended that you change it once the system is properly initialized/started.

  • subdir
    A comma-separated list of directories will be created during the initial process. There may be a use case when you need an additional directory - e.g., exports.

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

  • port
    Until the directory name is different (see the previously mentioned warning), the only "problem" in parallel environments is the "already used" port. With this parameter, you can set the port used for the mapping to be different than the TCP/8080.

    -port 8090

  • ver
    The version of midPoint to use. The tag published on the public registry contains the version in the tag. Using this attribute, you can easily change the required version without specifying the whole image name and complete tag (including the base OS).

    -ver 4.8.5

The other attributes can be used once you start with the advanced scenario(s).

Table 3. Available attributes
Attribute Description

-h

help - show available option(s)

-debug

Debug (show operation output for the troubleshooting purpose)

-fg

Foreground (keep attached / not starting on background)

-base <base_dir>

base directory (by default derived from the script location)
Used to calculate the location of the files.

-initpw <init_password>

Initial administrator password
Intended only for the first run. It is not meant to be used to change the password once the user is created.

-home <home_dir>

home directory (related to base_dir)
The name of the directory - the root of the directory structure for the midPoint instance.

-subdir <directories>

A comma-separated list of sub-directories to be created.

-uid <uid>

User ID for the processes in the container
The default value is taken from the currently logged user (current session).

-gid <gid>

Group ID for the processes in the container
The default value is taken from the currently logged user (current session).

-port <port>

TCP port used for the forwarding.
The TCP port used to redirect the communication. ( http://localhost:<port>/midpoint/ ).

-name <img_name>

Image name (without tag)
Used to construct the final image name for the configuration.

-ver <img_version>

Image version
Used to construct the final image name for the configuration.

-suffix <img_v_suffix>

Image version suffix
Used to construct the final image name for the configuration.

-exec <env_exec_cmd>

Command to run / control env.
The default value is docker or sudo docker in case the user is not a member of the docker group.

Exit codes

In case you decide to experiment with the script, there are several exit codes that could be returned. Once you show the help, it will be dynamically listed. At this moment, the following exit codes are "available":

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)
Was this page helpful?
YES NO
Thanks for your feedback