Installing MidPoint From Source Code

Last modified 26 Sep 2024 11:11 +02:00

This guide provides instruction for installing midPoint from the source code. It requires software development tools and some experience to build the product. This is recommended only for engineers that want to participate in midPoint development or have deeper interest in the source code. Everybody else will probably find installing distribution package or containers much easier.

MidPoint 4.0 and later

This guide applies to midPoint 4.0 and later. For guides that apply to older releases please see the release notes.

Before You Start

There are few things to check before you start the installation:

Make sure to see Release Notes for list of environments that are known to work and for the list of known issues in current release.
Make sure the System Requirements are met.
Development versions of midPoint are, quite obviously, not finished yet. There may be unfinished parts, bugs, instability and a variety of other problems. Use it at your own risk only.

Prerequisites

MidPoint is a Java application, therefore it requires Java platform to run on. Java 21 is a recommended platform for MidPoint 4.9.3. Alternatively, Java 17 can be used. Other Java platform versions are not supported. Java platform distributions based on OpenJDK are recommended. Other JDK builds (e.g. Oracle) may work as well, but those have limited support for midPoint (see release notes for the details).

JAVA_HOME environment variable should point to the Java installation path.

Please make sure you have full Java Development Kit (JDK), not just the runtime environment (JRE). Full set of development tools is needed, as you will be building midPoint from source code.

Git

The midPoint source is available from a Git server. You will need a suitable git client software to clone the source code. Many operating systems include that as a standard package. E.g. Debian-based Linux system can install it using apt:

sudo apt install git

Maven

MidPoint source code is built using Apache Maven.

Download and install Maven3: http://maven.apache.org/download.html

M2_HOME environment variable should point to the Maven installation path.

Installation

Getting The Source Code

MidPoint source code is hosted on GitHub:

GitHub project page	https://github.com/Evolveum/midpoint
Git repository HTTPS access	https://github.com/Evolveum/midpoint.git
Git repository SSH access	`git@github.com:Evolveum/midpoint.git`

GitHub project page

https://github.com/Evolveum/midpoint

Git repository HTTPS access

https://github.com/Evolveum/midpoint.git

Git repository SSH access

git@github.com:Evolveum/midpoint.git

Use your git client to clone the source code tree. For example, Linux system can use git command-line client:

git clone -b v4.9.3 https://github.com/Evolveum/midpoint.git

Running this command creates midpoint directory containing midPoint source code tree.

The -b option specifies midPoint version. You can ommit the option to get the latest development version of midPoint (master branch):

git clone https://github.com/Evolveum/midpoint.git

For more information about the source repository structure see Source Code.

On Windows, we highly recommend to add the following switch to the git clone command: --config core.autocrlf=false

Actually, you can use the switch on any platform. While in theory autocrlf works, it does not work well for midPoint projects. Don’t forget to adjust project settings for IDE accordingly (taken care of automatically when using IntelliJ IDEA).

Next to master branch there are available also support branches. After each release there is ready relevant support branch where are placed all the bug fixes until next release is done. It is working snapshot between releases.

These branches have the naming support-X.Y. E.g. for the LTS release 4.8(.x) there is support branch support-4.8.

Building MidPoint

Enter the directory with downloaded source code and execute either of the following commands:

mvn install

Complete build process also includes unit and integration tests, and it may take more than one hour. You can speed up the build by skipping automatic tests using the following command:

mvn install -DskipTests=true

After the successful build process there will be a binary distribution package located in dist/target directory.

Building the WAR file only

If the WAR file is all you need you can speed the build even further by skipping the packaging of the distribution archive. Use the following command to turn off the dist maven profile:

mvn clean install -DskipTests=true -P -dist

Please note the minus character (-) before profile name.
The resulting WAR file can be obtained from gui/admin-gui/target/midpoint.war

Running MidPoint

Continue with installation in the same way as for a binary release. See Installing MidPoint Server From Distribution Package page. However, you need to use your own freshly built distribution package from dist/target directory instead of downloading it.

Next Steps

MidPoint is a comprehensive system, and the source code is quite big. If you plan to work with midPoint source code, we strongly recommend getting an integrated development environment (IDE). Most midPoint developers are using IntelliJ IDEA and there is a short guide to set up IntelliJ IDEA for midPoint development. Eclipse Java IDE can also be used.

MidPoint has to store its own data in a database, which we call repository. MidPoint stores all the data there: users, roles, shadow objects representing accounts, configuration, everything.

MidPoint needs PostgreSQL database engine to do that. PostgreSQL is leading open source relational database engine. Since midPoint 4.4, midPoint can use features specific to PostgreSQL to its advantage (using native PostgreSQL repository implementation).

MidPoint also has support for other database engines. However, since midPoint 4.4, such support is deprecated. Do not use other database engines unless there are historic reasons, and you have a sound plan for migration to PostgreSQL.

The Repository Configuration page provides the instructions.

If you plan to participate in midPoint development, please see the Development Participation page. If you plan to contribute source code, the Code Contribution Guidelines page provides essential information.