Merge branch 'documentation' into documentation

# Conflicts: # docu/project_documentation.md

Merge branch 'documentation' into documentation
# Conflicts: # docu/project_documentation.md
Benjamin Rühl
2 parents a8a3ebca b67ee216
Showing 2 changed files with 74 additions and 19 deletions
README.md
docu/infrastructure.md
@@ -9,7 +9,8 @@ BeuthBot is a master project of the Beuth University of Applied Sciences Berlin.
 - [Application properties](#application-properties)
 - [Docker configuration](#docker-configuration)
 - [Local tunnel](#local-tunnel)
-- [Debugging](#debugging)
+- [Debug application](#debugging)
+- [Deploy application](#aeploy-application)
 - [Known issues](#known-issues)
 - [Used online sources](#used-online-sources)
@@ -50,7 +51,7 @@ The project should be cloned from the repository. For development it is possible
 With the following command it is possible to build the whole project. The construction of the project is possible during operation and before starting the server. In the first case the running server is automatically updated during operation.
-```
+```bash
     ./gradlew war
 ```
@@ -58,17 +59,17 @@ With the following command it is possible to build the whole project. The constr
 The application can be started with the following command:
-```
+```bash
     # Unix
     ./gradlew chatbotRun
 ```
-```
+```bash
     # Windows
     gradlew.bat chatbotRun
 ```
-```
+```bash
     # MacOS
     cd docker
     docker-compose up --build
@@ -89,17 +90,17 @@ In addition it is also possible to set up your own bot for example, in Telegram 
 The following command can be used to stop the running application:
-```
+```bash
     # Unix
     ./gradlew chatbotStop
 ```
-```
+```bash
     # Windows
     gradlew.bat chatbotStop
 ```
-```
+```bash
     # MacOS
     cd docker
     docker-compose down
@@ -176,30 +177,35 @@ MacOS:
 MacOS requires XCode and Homebrew in order to install NodeJS.
 XCode can be downloaded and installed for free via the App Store.
-To install Homebrew, open a terminal window and type`
-```
+To install Homebrew, open a terminal window and type
+
+```bash
     ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
 ```
 After Homebrew has completed installation, install NodeJS by typing:
-```
+
+```bash
     brew install node
 ```
 Finally install localtunnel by typing:
-```
+
+```bash
     npm install -g localtunnel
 ```
 If everything has worked correctly, you are now ready to use localtunnel.
 Using localtunnel is fairly easy, simply type:
-```
+
+```bash
     lt --port 8080
 ```
 Where the number entered after --port corresponds to the port you want localtunnel to route its HTTPS-Domain to.
 The localtunnel server can be slow and a little unreliable at times, but if everything goes well you should see something like:
-```
+
+```bash
     your url is: https://uawfhausjdj.localtunnel.me
 ```
 which is the url you can put in the first line of the `beuthbot.properties` file in the /docker/wildfly/volumes/conf` directory.
@@ -210,7 +216,7 @@ NOTE: Localtunnel tends to crash every now and then, displaying an error message
 <!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
-## Debugging
+## Debug application
 At the moment, the JBoss server is always started with open debugging ports. To attach to the running docker container process using IntelliJ, a remote debug configuration has to be created. To do so, perform the following steps:
@@ -223,6 +229,59 @@ At the moment, the JBoss server is always started with open debugging ports. To 
 <!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
+## Deploy application
+
+The following paragraph describes how the deplyoment is performed from a local Git repository to the production server. All development statuses have to be transferred to the `master` branch before performing the deployment. Just from the `master` branch it is possible to carry out the deployment on the productive server. To be able to perform the deplyment, it is necessary to be able to access the server via SSH. Then Git will transfer the status of the `master` branch to the server. This requires customizations on the server and in the local Git.
+
+### 1. Setup on the server
+
+On the server the following Git command have to be executed in the directory `home/<user>/`. Instead of the placeholder `<projectname>` the actual name of the project has to be used. The command creates a Git directory which includes all necessary files for a Git Hook.
+
+```bash
+git init --bare ~/<projectname>.git
+```
+
+After the Git folder has been successfully created, a new file with the name `post-receive` has to be created in the subfolder `<projectname>.git/hooks`. Afterwards the script has to be inserted into this file and the placeholders get changed by project-specific variables. The script will also start the `deployment.sh` script. This executes the build of the project and starts the appropriate Docker command. In addition, this script ensures that the `beuthbot.properties` file on the server is replaced by the corresponding productive file. In local development the `post-receive` and `deployment.sh` file can be found in the `scripts/` folder.
+
+```bash
+#!/bin/bash
+while read oldrev newrev ref
+do
+    # only checking out the master (or whatever branch you would like to deploy)
+    if [[ $ref =~ .*/master$ ]];
+    then
+        echo "Master ref received.  Deploying master branch to production..."
+        git --work-tree=/home/<user>/<projectname>/ --git-dir=/home/<user>/<projectname>.git/ checkout -f
+        cd /home/<user>/<projectname>/
+        ./scripts/deployment.sh
+    else
+        echo "Ref $ref successfully received. Doing nothing: only the master branch may be deployed on this server."
+    fi
+done
+```
+
+In addition a folder with the project name `<projectname>` has to be created on the server in the directory `home/<user>/`. This is where the code from the `master` branch is pushed.
+
+```bash
+mkdir ~/<projectname>
+```
+
+### 2. Use in a local development environment
+
+This step sets up a reference to the server on which the application is deployed. For this the following command must be executed. The placeholder `<user>` has to be replaced by the matching SSH user and the project `<projectname>` that has been set up on the server.
+
+```bash
+git remote add production ssh://<user>@<ip>:<port>/home/<user>/<projectname>
+```
+
+After the Git remote settings have been made the current state of the `master` branch can be pushed to the server using the following command.
+
+```bash
+git push production master
+```
+
+<!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
+
 ## Known issues
 The following issues are currently known in the application:
@@ -5,10 +5,6 @@ Each module is loosely connected through a Java Message Service. The application
 - see [docker compose file](../docker/docker-compose.yml)
-The productive project is represented by a separate Git repository in absent of a continuous integration server.
-Pushing into the master branch of this repository should automatically trigger a rebuild of the productive environment.
-- confer [post-receive](../scripts/post-receive) - Git hook for auto deploying the application
-
 ## Sub projects
 _**DISCLAIMER:** Please note that the following information is documented by the second project team who felt that a deeper look into the project structure should be a requirement for teams working on the project. This means that information is written 'as understood'. The original designers of the system had great knowledge of their architecture but sadly forgot to share it._