added documentation for deployment

hausdoerfer
1 parent 663586ee
Showing 2 changed files with 78 additions and 28 deletions
README.md
docu/project_documentation.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)
  
@@ -49,7 +50,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
 ```
  
@@ -57,17 +58,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
@@ -88,17 +89,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
@@ -159,30 +160,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.
@@ -193,7 +199,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 process using IntelliJ, a remote debug configuration has to be created. To do so, perform the following steps:
  
@@ -206,6 +212,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:
@@ -3,28 +3,19 @@ The hole project is build by gradle and divided into a couple of subprojects (cf
 Each module is loosely connected through a Java Message Service. The application is running on a Jboss Wildfly
 inside of a docker container. Another docker container is used for the Rasa backend.
  
-## Infrastructure
-- 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 this repository will automatically trigger a rebuild of the productive environment.
-- confer [post-receive](../scripts/post-receive) - Git hook for auto deploying the application
-
-### Subprojects
-
-#### MainBot
+## MainBot
 - [Canteen Parser](canteenParser.md) - web crawler for collecting data of the beuth university canteen
 - Common - holding common classes used by all other subprojects
 - [Drools](drools.md) - Business Rules Management System used to generate the right answer
 - Global - global available services
  
-#### Natural Language Processing
+## Natural Language Processing
 - [ApiAi](apiai.md) - simple RESTEasy client application calling googles Api.ai API
 - [Rasa](rasa.md) - simple RESTEasy client application calling the rasa backend rest API
  
-#### Messenger
+## Messenger
 - [Facebook](facebook.md) - Facebook Messenger connector
 - [Telegram](telegram.md) - Telegram Messenger connector
  
-#### Text <-> Speech Processing
+## Text <-> Speech Processing
 - [Bing Speech](binspeechapi.md) - REST client for Microsofts Bing Speech API
 \ No newline at end of file