# MOA ZS - README

This document gives instructions on how to build, test, and deploy MOA ZS.
See [the technical specification](docs/spec.md) 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](docs/changelog.md).

## 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](docs/howto-ssl-client-auth-with-apache.md) 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](docs/spec.md) and [application.yaml](src/test/resources/config/application.yaml) for more details.

### Deploy as Standalone Application

1.   Create a new directory that serves as the application's working directory.

         mkdir standalone

1.   Copy the `war` file into the applications working directory.

         cp target/moa-zs.war standalone/

1.   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](https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html#boot-features-external-config-application-property-files) for further details and alternative ways to configure the application.

1.   Start application.

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

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

1.  Copy the application package `moa-zs.war` to Tomcat's `webapps` directory.

        cp target/moa-zs.war $CATALINA_BASE/webapps/

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

1.  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](https://tomcat.apache.org/tomcat-9.0-doc/class-loader-howto.html)).
    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.

1.  Start tomcat.

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