# Installing MidPoint 3.5.1 "Einstein" Update 1 From Binary Distribution

## Introduction

This page describes the steps required to install midPoint from a binary distribution. This document describes the generic case suitable for trying out midPoint. For more complex installation scenarios please see Installation Guide.

 Release Notes Before you start the installation 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.

MidPoint is a Java web application distributed in a form of `WAR` archive. All that is essentially needed is to deploy it in a suitable container. This guide provides instructions to install midPoint in Apache Tomcat.

This document is somehow generic. This is done by purpose so it can be applied to a variety of operating systems and environments. Yet there are some more detailed guides for some environments that may be useful as companion to this document:

Environment Guide

Ubuntu Linux, Tomcat and PostgreSQL database

midPoint on Ubuntu, Tomcat, PostgreSQL HOWTO

## Before You Start

### Pre-requisites

#### 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 of 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

 Java 8 only MidPoint 3.5.1 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.1. It is finally the time to abandon obsolete technology and to move on.

#### Apache Tomcat

midPoint needs an application server. We recommend Apache Tomcat 8.x.

## Installation

 MidPoint 3.5.1 Binary Distribution

Unpack the archive file to a convenient location. Following instructions will refer to the relative paths inside this archive.

 Please do NOT set the unzipped directory as your MidPoint Home Directory. Doing so, "schema" directory would conflict with midPoint embedded schemas. Instead, create a new directory as described below.

### MidPoint Home Directory (midpoint.home)

If you intend to use custom connectors or schemas you need to create a directory anywhere on your system. This directory will be used to store your custom connector code, schemas, initial configuration and may also contains other files. MidPoint will populate that directory on first start. The directory will not be overwritten when midPoint is restarted or redeployed.

As an intended side-effect, this directory will also be used to store your embedded database repository data (H2).

If you don’t want to use custom connectors or you want just to try midPoint, you can skip this chapter and continue to the Initialize Database section.

#### Create the Directory

You can create your custom directory anywhere in your system. We often use locations such as `/opt/midpoint` or `/var/opt/midpoint` on linux platforms and `c:\midpoint` directory on windows platforms. The directory has to be writable by the application server.

See MidPoint Home Directory page for a description of the directory structure.

#### Tomcat "setenv.sh/setenv.bat" Customization

To actually use the Custom Directory, modify the `setenv.sh` script (UNIX) or `setenv.bat` batch file (Windows) located in <tomcat>/bin. If this file does not exist then create a new file. Set the "JAVA_OPTS" variable in this file. On UNIX machines add the line:

``````...
MIDPOINT_HOME="/var/opt/midpoint/"
JAVA_OPTS="$JAVA_OPTS -Dmidpoint.home=$MIDPOINT_HOME -Djavax.net.ssl.trustStore=\$MIDPOINT_HOME/keystore.jceks -Djavax.net.ssl.trustStoreType=jceks -server -Xms512m -Xmx2048m"
export MIDPOINT_HOME JAVA_OPTS
...``````

``````...
set JAVA_OPTS=%JAVA_OPTS% -Dmidpoint.home=c:/midpoint -Djavax.net.ssl.trustStore=c:/midpoint/keystore.jceks -Djavax.net.ssl.trustStoreType=jceks -server -Xms512m -Xmx2048m
...``````

This line sets up MidPoint Home Directory location, memory options and truststore location. It also overrides default JVM keystore. This is needed for proper SSL support in connectors, notifications and other libraries that are not under direct midPoint control. See Keystore Configuration page for more details.

### Configure Tomcat

Tomcat has a limitation of maximum size of POST data it accepts. This can cause problems when editing or importing large objects. So it is advisable to raise (or eliminate) the limit by editing the `server.xml` file, e.g.:

``<Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" maxPostSize="100000000"/>``

or

``<Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" maxPostSize="-1"/>``

### Initialize Database

MidPoint comes with an embedded database engine (H2) that is perfectly suitable for testing and demo installations. This database will be used by midPoint after the installation. Therefore there is no need to set up a separate database if installing midPoint for the first time. The database files will be stored in `midpoint.home` directory.

The database can later be changed to a full-scale database engine. The Repository Configuration page provides the instructions.

### Deploy midPoint

MidPoint appliation is deployed by using the `midpoint.war` file located in the `war` subdirectory of the distribution archive. To deploy midPoint WAR file, use the following steps:

1. Stop Tomcat if it’s already running.

2. Copy `midpoint.war` to `<tomcat>/webapps directory`.

3. Start Tomcat. It should pick up and deploy the "midpoint" application.

## Post-Installation Steps

5ecr3t

A home page of the midPoint console should be displayed. This is a pretty dynamic web application using AJAX for better user interaction. The look&feel is quite minimalistic now, we are working on an improvement just now.

If there is a problem, please check Tomcat logs in `<tomcat>/log/catalina.out` and `<tomcat>/log/idm.log`.

### Optional Post-Installation Steps

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.

### What Now?

For a quick introduction to use of midPoint please follow the instructions on First Steps page. Full Administration Interface is also available.

 MidPoint 3.5.1 Binary Distribution

Unpack the archive file to a convenient location. Following instructions will refer to the relative paths inside this archive.

## Start MidPoint

All that remains is to start midPoint server up:

Starting midPoint (Linux)
``bin/start.sh``
Starting midPoint (Windows)
``bin\start.bat``

## Try MidPoint

`http://localhost:8080/midpoint/`
Username `administrator` `5ecr3t`
User dashboard should be displayed after login. In case of any problems, please check midPoint logs in `var/log/` directory.