MOA ZS - README

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

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. 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.
2. Ensure that mod-proxy is installed and enabled.

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

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

5. 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 and application.yaml for more details.

Deploy as Standalone Application

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

   mkdir standalone

2. Copy the war file into the applications working directory.

   cp target/moa-zs.war standalone/

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

4. Start application.

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

5. 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/

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

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

4. Start tomcat.

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