This HOWTO describes an installation and configuration of midPoint in Ubuntu Linux environment. MidPoint will run in Apache Tomcat web container. Apache web server will be placed in front of it as a reverse proxy. MidPoint repository will be maintained in PostgreSQL database running on the same host.
Note: all commands specified in this tutorial should be run as
root. Therefore either prefix them with
sudo or execute
sudo -s at the beginning of installation session.
Install Java JDK
We recommend using the OpenJDK 8 that is distributed with Ububtu (16.04 LTS):
If you prefer Sun JDK or if there is no OpenJDK 8 in your distribution then download Sun JDK from oracle.com and install it. Just make sure it is JDK version 8.
Java 8 only
MidPoint 3.5 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. It is finally the time to abandon obsolete technology and to move on.
Installing JCE Extension
The JCE Unlimited Strength extension provides a full-strength cryptography for Java. It is usually good idea to install it if it is legal under your jurisdiction. The files can be downloaded from oracle.com. Look for Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files. Choose version appropriate for your JDK version.
Unzip the archive and copy the two jar files to
/opt/java/jre/lib/security. It may be a good idea to back up the original files before doing this.
Install Apache Tomcat
Download tomcat 8 binary installation package from Apache website.
Unpack the tomcat to
/opt. This creates
/opt/apache-tomcat-8.5.4 or similar directory. Make a symlink for easier management:
Create tomcat user (remember to make sure /usr/sbin/nologin is an allowed shell in /etc/shells file - otherwise the init.d script will fail):
Change ownership of the installed files:
Create init.d script for tomcat:
Add execution permissions to tomcat script:
We don't want tomcat to be accessible directly from the network. Therefore let's configure it to listen only on localhost address. Edit the
/opt/apache-tomcat/conf/server.xml file and add
address attribute to each
<Connector> definition. Like this:
Install and Configure Apache
Install Apache ubuntu package:
Configure the proxy to tomcat in appropriate apache site definition:
If midPoint is the only (or the main) application on this host then you might also want to configure a redirect:
Reload apache configuration:
Install PostgreSQL ubuntu package:
Create user in the database (remember the password):
Create a database:
Select appropriate SQL schema script for your midPoint version (Download script from Raw tab):
use appropriate tag directory using the example above
Execute the script to create database schema (tables, indexes, etc.):
(The "WARNING: there is no transaction in progress" is OK)
The database is now ready.
Deploy and Set Up midPoint
Stop tomcat (if it is running):
Download or build
midpoint.war. Place it into
Create midPoint home directory. This directory contains midpoint startup configuration, keystore, connector code and similar things. According to UNIX conventions the best place is perhaps
/var/opt directory but use whatever place suits your installation. Also make sure it can be accessed by tomcat:
Edit tomcat startup file
/opt/apache-tomcat/bin/catalina.sh to tweak its parameters. We need this to let midpoint know where is the location of its home directory and also to modify the default Java memory settings. Place this line somewhere near the beginning of the file:
Start tomcat now:
Tomcat should pick up the WAR file and deploy the application. This may take a minute or so. The
/opt/apache-tomcat/webapps/midpoint directory should appear. You can follow the deployment process by tailing
/opt/apache-tomcat/logs/catalina.out. You can watch pre process of midpoint startup and initialization by tailing
/opt/apache-tomcat/logs/idm.log (this happens after the deployment). After midpoint starts the directory
/var/opt/midpoint should be populated with several files and subdirectories.
Midpoint starts with a default settings. This means that it is using an embedded H2 database for storing files. We want to change this to PostgreSQL. The setting is in the midpoint home directory (
config.xml file. This file is read during midpoint start. Therefore let's first stop tomcat together with deployed midpoint:
config.xml file midpoint home directory (
/var/opt/midpoint). Change the
<repository> section to refer to the PostgreSQL database created above. Do not forget to substitute the real password for midpoint PostgreSQL user in the
Note that JDBC driver for PostgreSQL is already bundled in midPoint, there is no need to install it explicitly.
MidPoint initialized its embedded database repository during the first start. This is no longer needed and it may be deleted to free some space and avoid confusion. The databases are in
Now it is the time to start tomcat and midPoint:
Optional Post-Installation Steps
Change Encryption Key
Encryption is used in midPoint to protect sensitive parts of the database such as passwords. The encryption key is not stored in the database (that would be really meaningless). It is stored in standard Java JCE keystore that is located in midPoint home directory by default. First start of midPoint generates and encryption key for you. But it generates a short encryption key that is suitable both for use by export-limited and full-strength cryptography modules. Therefore is full-strength JCE extension was installed it is recommended to change the encryption key to a full-strength key. It can be achieved by
First stop tomcat:
Generate new key with a
That command will create a new 256-bit AES key with alias
strong. Now reconfigure midPoint to use the new key. Edit the
config.xml file to change encryption key alias. Also make sure a strong algorithm is specified:
Start tomcat again:
MidPoint is now up and running. You can access the administration gui at:
For more information how to customize and run midPoint please see: