From 59458d2a158c07b1e5d2ecab0be91c6de604b130 Mon Sep 17 00:00:00 2001 From: Manuel Bentele Date: Fri, 21 May 2021 17:06:34 +0200 Subject: [client,server] Add doc about how to build and configure server and client --- README.md | 18 ++++++++++++ dozentenmodul/README.md | 46 ++++++++++++++++++++++++++++++ dozentenmodulserver/README.md | 66 +++++++++++++++++++++++++++++++++++-------- 3 files changed, 119 insertions(+), 11 deletions(-) create mode 100644 README.md create mode 100644 dozentenmodul/README.md diff --git a/README.md b/README.md new file mode 100644 index 00000000..23eac65e --- /dev/null +++ b/README.md @@ -0,0 +1,18 @@ +# bwSuite & bwLehrpool-Server + +The bwSuite (bwLehrpool-Suite) and the bwLehrpool-Server are two applications (client and server) that are part of [bwLehrpool](https://www.bwlehrpool.de). More information about both applications and their configurations can be found in the detailed description of the two application sub-projects: + + - [bwSuite](dozentenmodul/README.md) + - [bwLehrpool-Server](dozentenmodulserver/README.md) + + +## Build +A build of both applications, namely the bwSuite and 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). + +Both applications can be built automatically by calling Maven with the following command line call: + +```shell +mvn clean package +``` + +A build of both applications creates Java archive files (\*.jar) that are placed into each sub-project's `target` directory. diff --git a/dozentenmodul/README.md b/dozentenmodul/README.md new file mode 100644 index 00000000..81b1e9c9 --- /dev/null +++ b/dozentenmodul/README.md @@ -0,0 +1,46 @@ +# bwSuite - Administration Client for Virtual Machines and Events + +The bwSuite (bwLehrpool-Suite) is a [bwLehrpool](https://www.bwlehrpool.de) client application to create and administrate virtual machines for study and coursework. With the help of the bwSuite it is possible to download ready-to-use virtual machine templates, which you can adapt locally for your purposes. Then, the bwSuite is capable to upload these personalized virtual machines to the [bwLehrpool-Server](../dozentenmodulserver/README.md), create new events and link the virtual machines to created events. Additionally, permissions can be set to grant selected or all users access to virtual machines. + + +## Build +A build of the bwSuite 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: + + - [ecp-client-lean](https://git.openslx.org/bwlp/ecp-client-lean.git) + - [master-sync-shared](https://git.openslx.org/bwlp/master-sync-shared.git) + - [proxy-vole](https://git.openslx.org/bwlp/proxy-vole.git) + +### Application +The bwSuite application can be built automatically by calling Maven with the following command line call: + +```shell +mvn clean package +``` + +A build of the bwSuite application creates a Java archive file (\*.jar) that can be found at `target/dozmod-client-*-jar-with-dependencies.jar`. + + +## Configuration + +### Logging +The logging of the bwSuite 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 bwSuite application during a build. + +#### Overwrite Logging Defaults +If logging configurations other than the defaults are required, the configuration file packaged into the bwSuite application can be overwritten by specifiying a custom configuration file. The custom configuration file is specified by execute the bwSuite application with the following command line call where `` is an absolute path to the custom configuration file and `` is a path to the built bwSuite application (Java archive file): + +```shell +java -Dlog4j.configuration=file: -jar +``` + +## Execution +The bwSuite application can be executed with the following command line call where `` is a path to the built bwSuite application (Java archive file): + +```shell +java -jar +``` 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 `` is a an absolute path to the custom configuration file and `` is a path to the built bwLehrpool-Server application (Java archive file): + +```shell +java -Dlog4j.configuration=file: -jar +``` + +## 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 `` is a path to the built bwLehrpool-Server application (Java archive file): + +```shell +java -jar +``` -- cgit v1.2.3-55-g7522