MidPoint 3.7 and later
This guide applies to midPoint 3.7 and later. For guides that apply to older releases please see the release notes.
This is the guide that describes how to install midPoint as a service, how to properly configure it and how to control it. This guide may be too complex if all you want is just to try midPoint. In that case please see Trying MidPoint page.
Introduction
This page describes the steps required to install midPoint Identity and Access Management from a binary distribution. MidPoint is a Java web application distributed in a form of a stand-alone self-contained server.
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.
- Check the System Requirements
Prerequisites
Java SE Development Kit 8
The development environment requires at least JDK 8. You can use OpenJDK wich might be already installed on your system or you can download JDK from Oracle.
JAVA_HOME environment variable should point to the JDK installation path.
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
Java 8 only
MidPoint 3.7 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.
Download MidPoint
Download the midPoint binary release from Evolveum download site.
Install MidPoint
Installing the Files
Unpack the archive file to an installation directory. Following directory locations are recommended:
| Operating system | Installation directory |
|---|---|
| Linux and other UNIX systems | /opt/midpoint |
| Windows | C:\Program Files\midpoint |
Following instructions will refer to the relative paths inside the installation directory.
MidPoint Home Directory
MidPoint Home Directory is a filesystem directory that midPoint uses to store initial configuration, cryptographic keys, log files and similar "variable" content. MidPoint home directory is located in the var subdirectory by default (e.g. /opt/midpoint/var). This location is acceptable for many installations. However, some installations may want to separate the static (read-only) parts of the installation and the dynamic (read-write) parts. In that case the midPoint home directory may be moved to any suitable location. This can be achieved simply by setting MIDPOINT_HOME environment variable (on UNIX systems) or manipulating the JVM options. Please see MidPoint Home Directory and Stand-Alone Deployment pages for details.
MidPoint home directory may be moved even after midPoint is installed. But setting the directory correctly before installation may save a lot of work later on.
MidPoint Repository
MidPoint comes with an embedded database engine (H2) that is suitable for testing and demo installations. This database will be used by midPoint after the installation unless other repository is specified. However, the embedded database is not supported for production installations. Therefore for a anything other than evaluation and demo installations it is strongly recommended to set up a full-scale database engine. The Repository Configuration page provides the instructions.
Cryptography
MidPoint encrypts some data to protect sensitive parts of the database such as passwords. 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 keytool utility. The Encryption and Keys page describes the procedure.
Post-Installation
Manual Run Control
MidPoint distribution package provides convenient scripts to start and stop midPoint service. Those scripts are locate in the bin directory. The purpose of those scripts is to start and stop midPoint manually. Those scripts are not interacting with any service control facility on operating systems (e.g. systemd). Those scripts just start and stop midPoint process.
Linux (UNIX)
Starting midPoint (Linux)
Stopping midPoint (Linux)
The start.sh and stop.sh scripts are just simple wrappers for midpoint.sh script. The midpoint.sh script is where all the action happens. This script can also be invoked directly:
Using midpoint.sh script (Linux)
The midpoint.sh script will process the script setenv.sh if it exists in the same directory (/bin). The script is a convenient place for customizing JVM properties, for example:
The midpoint.sh script may provide more run control and diagnostics capabilities in the future.
Windows
Starting midPoint (Windows)
Stopping midPoint (Windows)
The start.bat and stop.bat scripts are just simple wrappers for midpoint.bat script. The midpoint.bat script is where all the action happens.
The midpoint.bat script will process the script setenv.bat if it exists in the same directory (bin). The script is a convenient place for customizing JVM properties.
Setting Up a Service
Proper way to run midPoint on a server is to register it to the operating system service control facility. This procedure is inherently dependent on an operating system. Following pages provide specific instruction for individual operating systems: