Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Info
titleSource Code

This guide provides instruction for installing midPoint from the source code. It requires basic software development tools and some experience to build the product. This is recommended only for engineers that want to test the latest development version of midPoint and for developers who would like to participate in midPoint development. Everybody else will probably find installing from the binary build much easier.

Pre-requisites

Before You Start

Note
titleRelease Notes

Please 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.

Prerequisites

Java Development Kit 8

The development environment requires Java Development Kit (JDK) version 8. There are two viable options for Java development environment:

  • OpenJDK is an open source Java Development Kit. It is usually available as part of your operating system distribution (e.g. package openjdk-8-jdk in Debian/Ubuntu Linux). MidPoint is very well tested with OpenJDK and this is the recommended environment for midPoint development.
  • Oracle (Sun) JDK. Java Development Kit. This is a commercial Java Development Kit. It can be downloaded at http://www.oracle.com/technetwork/java/javase/downloads/index.html. These packages can easily used even on package-management-challenged operating systems.

You need just Java Standard Edition (SE) development kit. Java Enterprise Edition (EE) is not required.

Note
titleJava 8 or later is required

Java 7 or earlier Java versions are no longer supported (since midPoint 3.5). Java 7 is obsolete for many years. And even the public security updates are no longer available. It was time to move forward. We support only Java 8 now.

Once the JDK is installed it is installed, it is a best practice to have at least JDK 8. You can use OpenJDK wich might be already installed on your system of you can download JDK from Oracle.

JAVA_HOME environment variable should point to the JDK installation path. Strictly speaking this is not needed if the JDK is installed in a default location. However this location may vary depending on operating system and the JDK package use. Therefore setting the JAVA_HOME environment variable is s safe bet.

The packaged version of OpenJDK 8 is recommended JDK for Linux systems. Use one of following commands to install the package:

  • Debian/Ubuntu: sudo apt-get install openjdk-8-jdk

Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 8

Optional AES-128 is used by default for encrypt/decrypt operations, so JCE is not needed. If you want to use bigger key size, e.g. AES-256, then JCE is required for cryptographic operations. You can download it at http://www.oracle.com/technetwork/java/javase/downloads/index.html. After downloading zip file follow installation instructions written in README.txt

Apache Tomcat

midPoint needs an application server. Currently, Apache Tomcat 8.x or 7.x are supported. More application servers will be supported in later releases.

Apache Tomcat can be downloaded from http://tomcat.apache.org/download-80.cgi. The Apache Tomcat installation directory is further referenced as <tomcat>. In windows platform prefer downloading of zip file to downloading of windows installer as later do not populate bin directory with all batch files. You will start tomcat server via running the startup.bat file from <tomcat>\bin directory.

Even though we usually recommend using the packaged software on Linux, we do not have good experience with linux-packaged Tomcat. According to our experience it is better to actually download the latest version of Tomcat and use that. Explicitly-installed Tomcat is easier to control. Installation of Tomcat is just a matter of expanding the installation archive to the target directory. We recommend to use /opt/apache-tomcat-8.5.4 or /opt/tomcat or a similar directory.
Info
titlePackaged Tomcat on Linux
Note
titleJava 8 only

MidPoint is supported only on Java 8 platforms. MidPoint supported both Java 7 and Java 8 for several years. The support for Java 7 was deprecated in midPoint 3.4.1 and it was removed in midPoint 3.5.

Git

The midPoint source is available from a Git server at github. The details regarding Git, Git client software and Git server locations are described in Git page. Short summary of Git coordinates is provided in the following table.

Github URLGitHub project pagehttps://github.com/Evolveum/midpoint
Git Repository URLs
(public access)

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

git@github.com:Evolveum/midpoint.git

Branchmaster

Maven

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

Note
titleMaven 3

Previous midPoint version can be build only by using Maven 2. Current version can only be built using Maven 3.

M2_HOME environment variable should point to the Maven installation path.

The packaged version of Maven is recommended for Linux systems. Use one of following commands to install the package:

  • Debian/Ubuntu: sudo apt-get install maven

Prepare midPoint software

...

Prepare MidPoint Software

Get MidPoint

Get the source from our Git repository

...

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

The packaged version of Git is recommended for Linux systems. Use one of following commands to install the package:

  • Debian/Ubuntu: sudo apt-get install git

...

Build MidPoint From Sources

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

...

Complete build process also includes unit and integration tests and takes approx. 1 more than one hour. You can speed up the build by skipping automatic tests using the following command:

...

Tip
titleBuilding 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

...

Run MidPoint

...

...

...

The deployment is simply a matter of copying the WAR file to <tomcat>/webapps directory and starting Tomcat.

Development Environment

Theoretically any development environment can be used to develop midPoint, ranging from command-line and vim to a comprehensive IDEs. However there are two environments that we use in the midPoint core team on day-to-day basis and those are known to work (reasonably) well:

Othe IDEs and approaches should also work. NetBeans have been tried in the past (and it worked), but there is no recent setup guide. Command-line build works perfectly and it is used all the time.

Resolving Build Issues

Building in National Environments

MidPoint build includes a step that generates a code from schema files. This step is relying on XML libraries that are known to fail when using national (non-US) environments. Therefore the use of en_US.UTF-8 locale is strongly recommended for build. Do not worry, midPoint will be able to run in national environments after it is built. We have plans to fix these issues, but it looks like the problems go deep into XML libraries and therefore they cannot be easily fixed (probably the best would be to rewrite the code entirely). Therefore in the meantime please bear with us and use the US environment for the build.

There is also a similar problem when the source code or maven repository resides on filesystem with paths that include national characters. E.g. usernames with national characters may cause problems. The symptoms of this problem is a build error:

Code Block
org.xml.sax.SAXParseException; src-resolve: Cannot resolve the name 'xml:lang' to a(n) 'attribute declaration' component.

The solution is to move the source code and also the local maven repository to a folder that does not contain national characters. To use a different path for maven repository you can use a command-line option:

Code Block
mvn -Dmaven.repo.local=D:\devel\.m2\repository clean install

 

See Also