[client,server] Add doc about how to build and configure server and client

1 files changed, 55 insertions, 11 deletions

diff --git a/dozentenmodulserver/README.md b/dozentenmodulserver/README.md
index d5a48233..1a224197 100644
--- a/dozentenmodulserver/README.md
+++ b/dozentenmodulserver/README.md
@@ -1,28 +1,72 @@
-# dozmod-server - Server to manage virtual machine images
+# bwLehrpool-Server - Management Server for Virtual Machines and Events
+
+The bwLehrpool-Server is a [bwLehrpool](https://www.bwlehrpool.de) server application to manage virtual machines and events for study and coursework. Already created virtual machines can be uploaded to the bwLehrpool-Server to share those virtual machines with students and workgroup members as well as link them to events. A virtual machine download from the bwLehrpool-Server allows a customization of virtual machines locally for your purposes.
+
 
 ## Build
+A build of the bwLehrpool-Server requires the installation of the build automation tool [Maven](https://maven.apache.org) and the Java development kit [OpenJDK 8](https://openjdk.java.net/projects/jdk8).
+
+### Dependencies
+If a Maven offline build takes place (`mvn -o`), the following dependencies are required and must be built manually first:
 
-### Java package
-The dozmod-server can be built as a Java archive (.jar) using the following command line call:
+  - [master-sync-shared](https://git.openslx.org/bwlp/master-sync-shared.git)
+
+### Application
+The bwLehrpool-Server application can be built automatically by calling Maven with the following command line call:
 
 ```shell
-mvn package
+mvn clean package
 ```
 
-The built package can be found at `target/dozmod-server-*-jar-with-dependencies.jar`.
-
+A build of the bwLehrpool-Server application creates a Java archive file (\*.jar) that can be found at `target/dozmod-server-*-jar-with-dependencies.jar`.
 
-### Docker container
-A docker image of the dozmod-server and its required infrastructure can be built and started with the following command line call:
+### Docker Container
+A docker image of the bwLehrpool-Server and its required infrastructure can be built and started with the following command line call:
 
 ```shell
 mvn -P dozmod-server:start
 ```
 
-Note that a complete Docker infrastructure (images, containers, networks and volumes) is created and started after this call. To stop the dozmod-server container and its entire infrastructure, use the following command line call:
-
-The running containers can be stopped with the following command line call:
+Note that a complete Docker infrastructure (images, containers, networks and volumes) is created and started automatically after this call using [docker-compose](https://docs.docker.com/compose). To stop the bwLehrpool-Server container and its entire infrastructure, use the following command line call:
 
 ```shell
 mvn -P dozmod-server:stop
 ```
+
+
+## Configuration
+
+### Server
+The bwLehrpool-Server application requires a Java property configuration file for its operation. A template for this configuration file can be found at `setup/config.properties.tmpl`. The template can be finalized with the [dockerize](https://github.com/jwilder/dockerize) utility using the following command line call where `DOZMOD_*` are environment variables to finalize the content of the configuration file:
+
+```shell
+export DOZMOD_DATABASE_HOST="192.168.200.20"
+export DOZMOD_DATABASE_NAME="sat"
+export DOZMOD_DATABASE_USER="root"
+export DOZMOD_DATABASE_PASSWORD="dozmod"
+export DOZMOD_MASTER_SERVER="bwlp-masterserver.ruf.uni-freiburg.de"
+export DOZMOD_VSTORE_PATH="/mnt/bwLehrpool"
+
+# finalize the template content with values from environment variables
+dockerize -template setup/config.properties.tmpl:config.properties
+```
+
+### Logging
+The logging of the bwLehrpool-Server application to the console is implemented with [log4j](https://logging.apache.org/log4j).
+
+#### Default Logging Configurations
+The default logging configurations are specified in the property file under `src/main/properties/log4j.properties`. This configuration file is packaged automatically into the bwLehrpool-Server application during a build.
+
+#### Overwrite Logging Defaults
+If logging configurations other than the defaults are required, the configuration file packaged into the bwLehrpool-Server application can be overwritten by specifiying a custom configuration file. The custom configuration file is specified by execute the bwLehrpool-Server application with the following command line call where `<CONFIG>` is a an absolute path to the custom configuration file and `<APP>` is a path to the built bwLehrpool-Server application (Java archive file):
+
+```shell
+java -Dlog4j.configuration=file:<CONFIG> -jar <APP>
+```
+
+## Execution
+An execution of the bwLehrpool-Server application requires an already finalized bwLehrpool-Server configuration file located in the current working directory. This configuration file can be created from a configuration template as explained above. Then, the bwLehrpool-Server application can be executed with the following command line call where `<APP>` is a path to the built bwLehrpool-Server application (Java archive file):
+
+```shell
+java -jar <APP>
+```