diff --git a/midpoint/quickstart/index-new.adoc b/midpoint/quickstart/index-new.adoc new file mode 100644 index 00000000..9da8aa0b --- /dev/null +++ b/midpoint/quickstart/index-new.adoc @@ -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 `, for example: ++ +[source,bash] +---- +mkdir midpoint +---- + +. Navigate to the created directory by using `cd `. +. 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-.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-.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-.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-.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 <>, or +* run it with <> + +[[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-.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 <>, 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] +---- +_net +_midpoint_data +-midpoint_data-1 +-data_init-1 +-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- +---- + +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 <>. + + +== 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 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. +====