Skip to content

index.adoc

Latest commit

 

History

History
380 lines (302 loc) · 14.8 KB

index.adoc

File metadata and controls

380 lines (302 loc) · 14.8 KB

MidPoint Quick Start Guide

This guide helps you deploy midPoint on your local computer using Docker in minutes.

Introduction

This guide shows you how to deploy midPoint in Docker using a Bash script that we provide. You can deploy midPoint this way in a few minutes, even if you are 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 but it also works on macOS and Microsoft Windows.

There are also other, more granular ways to deploy midPoint. If you know your way around Docker, or if you want to use a different deployment method, refer to ../install/index.adoc for more options.

Prerequisites

Before you can deploy midPoint, make sure you have the following:

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

    Tip

    To check if you have Docker already installed on your computer, run docker --version in your terminal. This should return the Docker version, such as Docker version 27.5.1, build 9f9e405. If not, Docker is not in PATH and likely not installed at all.

  • Bash - Bash is a widely used shell on Linux-based systems. If you are on Linux or macOS, you probably have it installed already. On Windows, you can use the WSL2 layer which has the Bash shell.

  • Internet connection - During the initial setup, the deployment script pulls the required Docker images from the Docker hub. Once you deploy midPoint, you can work offline.

Get the script

  1. Open the Bash shell.

  2. Create a directory in which you want to host the midPoint instance by using mkdir <directory_name>, for example:

    mkdir midpoint

  3. Navigate to the created directory by using cd <directory_name>.

  4. Use curl to download the midPoint quickstart script.

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

    By default, the script will install the latest stable version of midPoint. This makes it easy for you to review the new midPoint features and updates.
    However, in some cases you may want to use a specific midPoint version. For example, when you already have another midPoint instance and you want to replicate a certain behavior, or when you want to be sure there will be no dependency issues in a newer version. To install a specific version of midPoint, change the version number in the midPoint_image_ver parameter in the quickstart script to the version of midPoint you want to install. See the supported releases page.

  5. Make the downloaded script executable:

    chmod 744 midpoint-quickstart.sh

Use the script

Quick-install midPoint

  1. Open the Bash shell.

  2. Navigate to the directory to which you have downloaded the midPoint quickstart script.

  3. Run the script with the start argument:

    ./midpoint-quickstart.sh start

  4. When prompted, type a new admin password that complies with the midPoint password policy, or press Enter for an automatically generated password.

    Note

    Make sure you remember or take note of the password before you close the Bash. For security reasons, it is also recommended to change the password after logging into midPoint as the password can be retrieved from Bash logs.

  5. Go to the address provided by the script in your web browser to access your newly deployed midPoint.
    Check the script output for both the address and your login credentials. The output will look similar to this:

    Example 1. Sample output of the start command
    $ ./midpoint-quickstart-4.9.3.sh start
Enter your new admin password.
The password must:
 - be at least 8 characters long,
 - contain one number,
 - contain one upper case,
 - contain one lower case letter
For automatically generated password in midPoint, leave blank and press ENTER.

4ToBeamUpEnergize
Fresh installation  -  creating home folder and setting up midPoint...
[+] Running 5/5
 ✔ Network midpoint-quickstart-mzjtbs_net                      Created     0.0s
 ✔ Volume "midpoint-quickstart-mzjtbs_midpoint_data"           Created     0.0s
 ✔ Container midpoint-quickstart-mzjtbs-midpoint_data-1        Healthy     6.8s
 ✔ Container midpoint-quickstart-mzjtbs-data_init-1            Exited      6.8s
 ✔ Container midpoint-quickstart-mzjtbs-midpoint_server-1      Healthy     21.8s

Starting midPoint...
To access the WEB GUI go to: http://localhost:8080/midpoint/
Username: administrator
Initial password: 4ToBeamUpEnergize (recommended to change in midPoint for increased security)
Tip
 You can stop the installation process at any time by pressing CTRL + C.

Quick-remove midPoint

  1. Open your Bash.

  2. Navigate to the directory to which you have downloaded the script.

  3. Run the script with the delete argument:

    ./midpoint-quickstart.sh delete

  4. Once the script finishes, midPoint is removed from your environment, including its containers, volumes, images, and local data.

All script options

There are more ways to use the quickstart script. You can either:

Interactive menu

  1. Open your Bash shell.

  2. Navigate to the directory to which you have downloaded the script.

  3. Run the script:

    ./midpoint-quickstart.sh

  4. This starts an interactive menu that looks as follows:

    +------------------------------+
|        -- MAIN MENU --       |
|------------------------------|
| (S)tart midPoint             |
| (I)nformation                |
| (L)ogs, then (b)ack          |
+------------------------------+
| (RES)et to factory settings  |
| (DEL)ete midPoint            |
+------------------------------+
| (Q)uit and stop midPoint     |
+------------------------------+

  5. In the script’s interactive menu, type a shortcut in parentheses and press the Enter key:

    Table 1. Quickstart script options
    Option Description

    (S)tart midPoint

    • Starts midPoint using Docker Compose (if it has already been deployed), or

    • deploys a new midPoint instance (if no existing instance has been found in the current directory).
      When deploying a new instance, you will be prompted for an initial password that has to comply the with the midPoint password policy. If you press Enter, a password will be generated for you automatically. Depending on your Internet connection, this operation may take up to a few minutes.
      Once the deployment has finished, you are shown the address to access midPoint on in your web browser, and the login credentials.

      Note

      Make sure you remember or take note of the password before you close the Bash. For security reasons, it is also recommended to change the password after logging into midPoint as the password can be retrieved from Bash logs.

    (I)nformation

    Gives you information on the the midPoint version, the installation status, environment details, etc.

    (RES)et to factory settings

    Resets midPoint to factory settings, i.e., it deletes the database, including the password, and prompts you to enter a new admin password for the midPoint instance.
    If midPoint is running when reset is invoked, it will be automatically restarted once the reset operation is completed.

    (DEL)ete midPoint

    Deletes midPoint altogether, including its containers, volumes, images, local data, and the password.

    (Q)uit and stop midPoint

    Shuts down midPoint and quits the interactive menu.

Script command line arguments

In addition to the interactive menu, you can also run the script in the command line with the following arguments:

Table 2. Script command line arguments
Option Description

start

Starts midPoint using Docker Compose (if it has already been deployed), or deploys a new midPoint instance (if no existing instance has been found in the current directory).
You can define the following additional arguments:

  • --port or -p - Selects the number of the port (up to 65535) on which midPoint will run.
    By default, the port 8080 is used. If the script detects a port is already used, the port number will be automatically incremented by 1.

  • --password or -w - Sets the initial password for midPoint. This only applies when the midPoint environment is first being deployed, and it is ignored in subsequent runs. Note that your password has to comply with the midPoint password policy.

    Note

    Make sure you remember or take note of the password before you close the Bash. For security reasons, it is also recommended to change the password after logging into midPoint as the password can be retrieved from Bash logs.

  • name or -n - Sets the name for the midPoint Docker containers, volumes, and network. This only applies when the midPoint environment is first being deployed, and it is ignored in subsequent runs. Custom naming Docker containers only accepts the following characters: lowercase letters, numbers, dashes, and underscores (an underscore cannot be the first character). Docker containers are named as follows:

    <custom-name>_net
<custom-name>_midpoint_data
<custom-name>-midpoint_data-1
<custom-name>-data_init-1
<custom-name>-midpoint_server-1

info

Gives you information on the midPoint version, the installation status, environment details, etc.

yaml

Prints the Docker Compose configuration YAML file that is used by the script.

logs

Displays logs for the running midPoint container. Press the "b" key to quit displaying the logs.

stop

Shuts down the midPoint Docker container.

reset

Resets midPoint to factory settings, i.e., it deletes the database, including the password, and prompts you to enter a new admin password for the midPoint instance.
If midPoint is running when reset is invoked, it will be restarted once the reset operation is completed.

delete

Deletes midPoint altogether, including its containers, volumes, images, local data, and the password.

help

Displays the available attributes for the script.

Multiple instances

You can use the midPoint quickstart script to deploy multiple midPoint instances.

To do so, run the script in a separate folder for each instance.

The quickstart script uses Docker Compose to create and maintain the midPoint containers. By default, Docker containers will be named as follows:

midpoint-quickstart-<hash><container>

where the hash is a unique string that prevents clashes in Docker container naming when there are multiple midPoint instances, and container represents a specific container, such as _midpoint_data or -data-init-1.

You can customize the midpoint-quickstart part of container names for better orientation by using the -n argument when running the script.

File paths in Docker containers

When you learn to work with midPoint, you can, 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.

Under the hood, midPoint runs inside Docker containers orchestrated by a Docker Compose file. This setup ensures that midPoint works seamlessly on your machine without requiring you to manage the environment manually. Our goal is to enable you to benefit from Docker’s capabilities without having to interact directly with containers or use Docker commands in most cases.

Quickstart script structure

When you use the quickstart script, it automatically creates a directory named midpoint-home in the location where the script was executed. This directory acts as the midPoint home directory and contains several subfolders that correspond to specific paths inside the Docker container. These folders are mounted into the container so that midPoint can access their contents.

Table 3. Container subfolders
Subfolder Purpose

import

Use this folder to add files for import, e.g. CSV files for the built-in CSV connector. When configuring the connector in midPoint, specify the internal path so that midPoint can access the file: /opt/midpoint/var/import/file-name.csv.

log

Contains all log files generated by midPoint. You can inspect them directly on your host system without entering the container.

schema

Use this folder to store custom XML schema definitions to extend or customize midPoint configuration. Updating schemas using this folder typically requires restarting midPoint. For more details, see Schema customization documentation.

icf-connectors

Place custom ICF connectors here if you want to use your own connectors instead of the built-in ones. For more information, see Connectors documentation.

Working directly with Docker

In Docker, you can access all midPoint configuration and data within the container. Inside the midPoint container, the home directory and all its subfolders are located under:

/opt/midpoint/var/

You can enter the container and inspect or modify files directly as follows:

  1. List your Docker containers by running docker ps.
    You will see an output similar to this one:

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

  2. Enter a container:

    docker exec -it <midpoint-container-id> bash
cd /opt/midpoint/var/
    Tip

    • You can use the find command to search for files, and the exit command to exit the container console.

    • Unless you need to cover a more complicated scenario, it is easier to access your files from the midpoint-home directory on your host system than from inside of a container.