Skip to content

add docs for new quickstart script #56

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jirihuf wants to merge 2 commits into
base: master
Choose a base branch
from
Open

add docs for new quickstart script #56

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
feb836f
add docs for new quickstart script
jirihuf Oct 16, 2025
a579ff4
add versioning to quickstart
jirihuf Oct 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
381 changes: 381 additions & 0 deletions midpoint/quickstart/index-new.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,381 @@
= MidPoint Quick Start Guide
:page-nav-title: Quick Start Guide
:page-display-order: 10
:page-liquid:
:toclevels: 2
:page-upkeep-status: green
:page-keywords: [ 'quickstart', 'quickstart script', 'start script" ]
:page-description: This guide helps you deploy midPoint on your local computer using Docker in minutes.
:hide:
:page-toc: top

// will need to update the script name in the command below

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 link:https://docs.docker.com/compose/[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 xref:../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 link:https://docs.docker.com/engine/install/[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 link:https://en.wikipedia.org/wiki/PATH_(variable)[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

. Open the Bash shell.
. Create a directory in which you want to host the midPoint instance by using `mkdir <directory_name>`, for example:
+
[source,bash]
----
mkdir midpoint
----

. Navigate to the created directory by using `cd <directory_name>`.
. Use `curl` to download the midPoint quickstart script for the version of midPoint that you want to deploy.
+
[source,bash]
----
curl -O https://raw.githubusercontent.com/Evolveum/midpoint-docker/master/midpoint-quickstart-<version>.sh
----
+
For example:
+
[source,bash]
----
curl -O https://raw.githubusercontent.com/Evolveum/midpoint-docker/master/midpoint-quickstart-4.9.3.sh
----
+
If you are not sure about the version, go to link:https://raw.githubusercontent.com/Evolveum/midpoint-docker/master/midpoint/[GiHub] and download the script for the latest version of midPoint.

. Make the downloaded script executable:
+
[source,bash]
----
chmod 744 midpoint-quickstart-<version>.sh
----

== Use the script

=== Quick-install midPoint

. Open the Bash shell.
. Navigate to the directory to which you have downloaded the midPoint quickstart script.
. Run the script with the `start` argument:
+
[source,bash]
----
./midpoint-quickstart-<version>.sh start
----

. When prompted, type a new admin password that complies with the xref:/midpoint/reference/security/authentication/administrator-initial-password/#default-password-policy[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.
====

. 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:
+
[[start_output]]
.Sample output of the `start` command
====
[source,bash]
----
$ ./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

. Open your Bash.
. Navigate to the directory to which you have downloaded the script.
. Run the script with the `delete` argument:
+
[source,bash]
----
./midpoint-quickstart-<version>.sh delete
----

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

[[interactive-menu]]
=== All script options

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

* Use its <<interactive,interactive menu>>, or
* run it with <<arguments,arguments>>

[[interactive]]
==== Interactive menu
. Open your Bash shell.
. Navigate to the directory to which you have downloaded the script.
. Run the script:
+
[source,bash]
----
./midpoint-quickstart-<version>.sh
----

. This starts an interactive menu that looks as follows:
+
[source,bash]
----
+------------------------------+
| -- 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 |
+------------------------------+
----

. In the script's interactive menu, type a shortcut in parentheses and press the *Enter* key:
+
.Quickstart script options
[%autowidth]
|===
| Option | Description

| (S)tart midPoint
a| * 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 xref:/midpoint/reference/security/authentication/administrator-initial-password/#default-password-policy[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.

|===

[[arguments]]
==== Script command line arguments

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

.Script command line arguments
[%autowidth]
|===
| Option | Description

a| `start`
a| 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 xref:/midpoint/reference/security/authentication/administrator-initial-password/#default-password-policy[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:
+
[source,xml]
----
<custom-name>_net
<custom-name>_midpoint_data
<custom-name>-midpoint_data-1
<custom-name>-data_init-1
<custom-name>-midpoint_server-1
----

a| `info`
| Gives you information on the midPoint version, the installation status, environment details, etc.

a| `yaml`
| Prints the Docker Compose configuration YAML file that is used by the script.

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

a| `stop`
| Shuts down the midPoint Docker container.

a| `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.

a| `delete`
| Deletes midPoint altogether, including its containers, volumes, images, local data, and the password.

a| `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 link:https://docs.docker.com/compose/[Docker Compose] to create and maintain the midPoint containers.
By default, Docker containers will be named as follows:

[source,xml]
----
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 <<arguments,running the script>>.


== File paths in Docker containers

When you learn to work with midPoint, you can, for instance, xref:/midpoint/reference/admin-gui/resource-wizard/create-resource-using-wizard/[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.

.Container subfolders
[%autowidth,cols="1,3",options="header"]
|===
| Subfolder | Purpose

a| `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`.

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

a| `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 xref:/midpoint/reference/schema/[Schema customization documentation].

a| [nowrap]#`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 xref:/connectors/[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:

[source,bash]
----
/opt/midpoint/var/
----

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

. List your Docker containers by running `docker ps`. +
You will see an output similar to this one:
+
[source,bash]
----
CONTAINER ID IMAGE COMMAND ...
41b8ffa427ff evolveum/midpoint:4.9.2-alpine "/opt/midpoint/bin/m…" ...
98fb6ba2a28f postgres:16-alpine "docker-entrypoint.s…" ...
----

. Enter a container:
+
[source,bash]
----
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.
====