# MOA ZS - README

This file 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.

## Build Instructions

Compilation and Runtime Requirements:
- openJDK 12 (OpenJDK 11 has an unfixed bug [1] that prevents the completion of TLS handshakes.)

### 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.
The following guide explains how to set up TLS and Client Authentication with Apache 2.

#### Quick Guide: Set Up SSL (inc. Client Authentication) in Apache 2.

This guide is only needed for running all tests.
Some tests require SSL protection of the service endpoint with SSL Client Authentication.
Here's a quick guide how to set up an Apache 2 service on localhost as a SSL terminating reverse proxy to the zusemsg endpoint that runs on <http://localhost:8081/>.

1.   Install Apache 2.
1.   Ensure that mod-proxy is installed and enabled.
1.   In `default-ssl.conf` add the following lines to proxy requests from `https://localhost/zusemsg` to `http://localhost:8081`:

     ```
     ProxyRequests off
     ProxyPass /zusemsg/ http://localhost:8081/
     ProxyPassReverse /zusemsg/ http://localhost:8081/
     <Proxy *>
       Order allow,deny
       allow from all
     </Proxy>
     ```

1.   Use certificate and key provided in this repository for the TLS connection and add the following directives to `default-ssl.conf`:

     ```
     SSLCertificateFile <path/to/repo/ssl/server>/server.localhost.cert.pem
     SSLCertificateKeyFile <path/to/repo/ssl/server>/server.localhost.key.pem
     SSLCertificateChainFile <path/to/repo/ssl/server>/ca-chain.cert.pem
     ```

1.   Trust the client certificate with the following directive in `default-ssl-conf`:

     ```
     SSLCACertificateFile <path/to/repo/ssl>/trusted-cas-bundle.pem
     ```


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

## Deployment

After packaging the application to a `war` file, the application can 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>.

# Footnotes

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