MOA ZS - README

This document gives instructions on how to build, test, and deploy MOA ZS. See the technical specification for a more detailed description of MOA ZS and how it can be configured. For changes between release versions (and especially between MOA ZS v1 and MOA ZS v2), see the changelog.

Build Instructions

Compilation and Runtime Requirements:

OpenJDK 12 (OpenJDK 11 has an unfixed bug [1] that prevents the completion of TLS handshakes.)
Apache Maven (tested with Apache Maven 3.6.0)

Run Unit Tests

Command:

mvn test

Run Integration Tests

Integration tests start with the prefix IT. Run them with the following command:

mvn test -P integration-tests

Run All Tests

Command:

mvn test -P all-tests

Note that some integration tests (prefix ITSSL) rely on a TLS connection and Client Authentication. This guide explains how to set up TLS and Client Authentication with Apache 2.

Package to .war

The application can be packaged to a web application archive by running the following command:

mvn package

Find the war file in the target/ folder.

Download

You can download a ready-to-deploy web application archive (.war) of MOA ZS from https://apps.egiz.gv.at/releases/moa-zs/.

Deployment

After obtaining the war file, MOA ZS needs to be configured and can then be deployed into a servlet container or as a standalone application.

Configuration

The folder src/test/resources/config serves as a template for configuring MOA ZS. This folder can be used as-is for deploying MOA ZS in a test or development environment. You may apply changes to this folder to fit the needs of a productive environment. See specification.md and application.yaml for more details.

Deploy as Standalone Application

Create a new directory that serves as the application's working directory.
```
 mkdir standalone
```
Copy the war file into the applications working directory.
```
 cp target/moa-zs.war standalone/
```
Copy the directory test/main/resources/config/ into the applications working directory.
```
 cp src/test/resources/config standalone/ -r
```
If you rename this folder, the application might not find the configuration file application.yaml. Consult Spring Doc: External Configuration for further details and alternative ways to configure the application.

Start application.

 (cd standalone && java -jar moa-zs.war)

The app2mzs service is reachable under http://localhost:$SERVER_PORT/services/mzs. The zuse2app service is reachable under http://localhost:$SERVER_PORT/services/msg.

Deploy to Tomcat Container

Copy the application package moa-zs.war to Tomcat's webapps directory.
```
cp target/moa-zs.war $CATALINA_BASE/webapps/
```
Create a copy of the directory test/main/resources/config/ ($MZS_CONFIG being the path to the configuration folder)
```
cp test/main/resources/config/ $MZS_CONFIG
```
Ensure that the spring-boot application finds $MZS_CONFIG/application.yaml. Option a) Add the folder $MZS_CONFIG to the class path of the web application, e.g. by specifying the common.loader property (see Tomcat's Class Loader How-To). Option b) Set the system property spring.config.location to $MZS_CONFIG/application.yaml. In that case, make sure that all paths in $MZS_CONFIG/application.yaml are absolute paths.
Start tomcat.
The app2mzs service is reachable under http://localhost:$TOMCAT_PORT/moa-zs/services/mzs. The zuse2app service is reachable under http://localhost:$TOMCAT_PORT/moa-zs/services/msg.

Directory Layout

In this repository you will find the following:

src : MOA ZS source code.
docs : Documentation.
curl : Example requests to check if the service is up and running on localhost.

Footnotes

[1] https://bugs.openjdk.java.net/browse/JDK-8214098