edu / BeuthBot_WS17 · Commits

Commit be1d54be5aaf4b2c8af717c70b13cad2791da90e

Authored by hausdoerfer
1 parent aa62787f
build: skipped

adapted existing documentation and added postman collection

Inline Side-by-side
Showing 2 changed files with 224 additions and 27 deletions
README.md
  View file @be1d54b
1 -# BHT-Chatbot  
2 -Master-Projekt SS2017 Medieninformatik  
3 -<!-- MarkdownTOC --> 1 +# BeuthBot
  2 +
  3 +BeuthBot is a master project of the Beuth University of Applied Sciences Berlin. This implementation is the work of media informatic students from semesters SS2017 and WS2017/18.
4 4
5 - [Requirements](#requirements) 5 - [Requirements](#requirements)
6 -- [Main TechStack](#main-techstack) 6 +- [Technologies](#technologies)
  7 +- [Firtst steps](#firtst-steps)
7 - [Project documention](#project-documention) 8 - [Project documention](#project-documention)
8 -- [Run and stop the application](#run-and-stop-the-application) 9 +- [Application properties](#application-properties)
  10 +- [Docker configuration](#docker-configuration)
  11 +- [Local tunnel](#local-tunnel)
  12 +- [Debugging](#debugging)
  13 +- [Known issues](#known-issues)
9 - [Used online sources](#used-online-sources) 14 - [Used online sources](#used-online-sources)
10 15
11 -<!-- /MarkdownTOC --> 16 +<!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
12 17
13 ## Requirements 18 ## Requirements
  19 +
14 - Java 8 to build the application 20 - Java 8 to build the application
15 -- a running docker daemon to start application server 21 +- Docker daemon to start application server
16 22
17 -## Main TechStack  
18 -- Gradle 3.5  
19 -- Docker 23 +<!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
  24 +
  25 +## Technologies
  26 +
  27 +- Oracle Java 8
  28 +- Gradle Build - build system
  29 +- Postgres SQL - relational database
  30 +- Adminer - database administration
20 - WildFly 10 31 - WildFly 10
  32 +- Docker
21 33
22 -## Project documention  
23 -You can find the whole project documentation under [project_documentation](docu/project_documentation.md). 34 +<!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
24 35
25 -## Run and stop the application  
26 -Go to project path and executes the following gradle tasks to start/stop the application:  
27 - ```bash  
28 - # Unix based  
29 - ./gradlew chatbotRun  
30 - ./gradlew chatbotStop 36 +## Firtst steps
  37 +
  38 +The following five steps clarify what is necessary to set up the BeuthBot for the first time. Most of the steps are also useful during development to ultimately test the changes in the application.
  39 +
  40 +All commands are listed in the following five steps and can be executed from the project path. If this is different than this is indicated accordingly. The commands may differ depending on which operating system is used.
  41 +
  42 +### 1. Set up integrated development environment
  43 +
  44 +The project should be cloned from the repository. For development it is possible to use IDE Intelij. The cloned project can then be imported into the IDE as Gradle project.
  45 +
  46 +- <https://git.ziemers.de/edu/BeuthBot.git>
  47 +
  48 +### 2. Execute project build
  49 +
  50 +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.
  51 +
  52 +```
  53 + ./gradlew war
  54 +```
31 55
  56 +### 3. Run application
  57 +
  58 +The application can be started with the following command:
  59 +
  60 +```
  61 + # Unix
  62 + ./gradlew chatbotRun
  63 +```
  64 +
  65 +```
32 # Windows 66 # Windows
33 gradlew.bat chatbotRun 67 gradlew.bat chatbotRun
34 - gradlew.bat chatbotStop 68 +```
35 69
  70 +```
36 # MacOS 71 # MacOS
37 - # you need to execute the docker commands directly  
38 cd docker 72 cd docker
39 docker-compose up --build 73 docker-compose up --build
40 - docker-compose down  
41 ``` 74 ```
  75 +
  76 +### 4. Test application
  77 +
  78 +After the application has started the following two endpoints of the server are easily accessible via the browser:
  79 +
  80 +- WildFly Server Manager: <http://localhost:9990/>
  81 +- Rasa: <http://localhost:5000/parse?q=Hello>
  82 +
  83 +It is possible to use a Postman Collection to test the configured endpoints for Telegram and Facebook. The `docu/postman/` directory includes a Postman collection containing corresponding endpoints. The JSON file `beuth-bot.json` can be imported into Postman. If changes are made to the Postman collection, the service of the JSON file should be increased accordingly.
  84 +
  85 +In addition it is also possible to set up your own bot for example, in Telegram and test it with the local server. For this however a local tunnel must be set up to make the application visible to the outside. For details see the section [Local tunnel](#Local tunnel).
42 86
43 -The following ports are mapped to host:  
44 -- 8080 -> 8080  
45 -- 8787 -> 8787 (Remote Debug Port)  
46 -- 9990 -> 9990 (WildFly Server Manager) 87 +### 5. Stop application
47 88
48 -If all went well, you should see the application appearing at [localhost:8080/bht-chatbot](http://localhost:8080/bht-chatbot) 89 +The following command can be used to stop the running application:
  90 +
  91 +```
  92 + # Unix
  93 + ./gradlew chatbotStop
  94 +```
  95 +
  96 +```
  97 + # Windows
  98 + gradlew.bat chatbotStop
  99 +```
  100 +
  101 +```
  102 + # MacOS
  103 + cd docker
  104 + docker-compose down
  105 +```
  106 +
  107 +<!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
  108 +
  109 +## Project documention
  110 +
  111 +In addition to this general documentation, the directory `docu/` also contains the [project_documentation](docu/project_documentation.md). This section also discuss the individual modules of the application.
  112 +
  113 +<!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
  114 +
  115 +## Application properties
  116 +
  117 +Settings for this application can be found in the `beuthbot.proterties` file. This is located in the directory `docker/wildfly/volumes/conf/`. The file is automatically entered in the Tomcat server during deployment and is used for configuration.
  118 +
  119 +<!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
  120 +
  121 +## Docker configuration
  122 +
  123 +The Docker configurations can be found in the `docker-compose.yml` file. This is stored in the directory `docker/`. Furthermore you can find the `Dockerfile` file in the folder `docker/wildfly/`. The following port mappings are set in the Docker files:
  124 +
  125 +### Backend
  126 +
  127 +Internal port of the container: `8080`
  128 +External port from the container: `8080`
  129 +
  130 +
  131 +### WildFly server manager
  132 +
  133 +Internal port of the container: `9990`
  134 +External port from the container: `9990`
  135 +
  136 +### Database
  137 +
  138 +Internal port of the container: `5432`
  139 +External port from the container: `5432`
  140 +
  141 +### Database administration
  142 +
  143 +Internal port of the container: `8080`
  144 +External port from the container: `8081`
  145 +
  146 +<!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
  147 +
  148 +## Local tunnel
  149 +
  150 +- <https://github.com/localtunnel/localtunnel/>
  151 +
  152 +<!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
  153 +
  154 +## Debugging
  155 +
  156 +At the moment, the Spring Boot server is always started in debug mode. To attach the process using IntelliJ, a remote debug configuration has to be created. To do so, perform the following steps:
  157 +
  158 +- Go to `Run` -> `Edit Configurations...`
  159 +- Add a new configuration using the button in the top left corner of the dialog
  160 +- Choose `Remote`
  161 +- Assign a name, ignore the arguments section and enter port `8787` (`localhost`) in the settings section
  162 +- click `OK` and select the new configuration at the top right of the toolbar if it has not been selected automatically
  163 +- run the configuration using the `Debug` button
  164 +
  165 +<!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
49 166
50 ## Known issues 167 ## Known issues
51 -- The usage of `./gradlew chatbotRun` is not working under Mac OSX 168 +
  169 +The following issues are currently known in the application:
  170 +
  171 +### Gradlew
  172 +
  173 +- The `./gradlew chatbotRun` command does not work on Mac OS X
  174 +- The general build command `./gradlew build` causes errors
  175 +
  176 +### Wildfly
  177 +
  178 +- During the boot process of the Wildfly server, the error `Mount point not found` occurs
  179 +
  180 +<!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
52 181
53 ## Used online sources 182 ## Used online sources
54 - [Markdown CheetSheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) 183 - [Markdown CheetSheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
docu/postman/beuth-bot.json 0 → 100644
  View file @be1d54b
  1 +{
  2 + "variables": [],
  3 + "info": {
  4 + "name": "beuth-bot-v1",
  5 + "_postman_id": "",
  6 + "description": "",
  7 + "schema": "https://schema.getpostman.com/json/collection/v2.0.0/collection.json"
  8 + },
  9 + "item": [
  10 + {
  11 + "name": "Facebook",
  12 + "description": "",
  13 + "item": []
  14 + },
  15 + {
  16 + "name": "Rasa",
  17 + "description": "",
  18 + "item": [
  19 + {
  20 + "name": "Hello",
  21 + "request": {
  22 + "url": {
  23 + "raw": "http://localhost:5000/parse?q=Hello",
  24 + "protocol": "http",
  25 + "host": [
  26 + "localhost"
  27 + ],
  28 + "port": "5000",
  29 + "path": [
  30 + "parse"
  31 + ],
  32 + "query": [
  33 + {
  34 + "key": "q",
  35 + "value": "Hello",
  36 + "equals": true,
  37 + "description": ""
  38 + }
  39 + ],
  40 + "variable": []
  41 + },
  42 + "method": "GET",
  43 + "header": [],
  44 + "body": {},
  45 + "description": ""
  46 + },
  47 + "response": []
  48 + }
  49 + ]
  50 + },
  51 + {
  52 + "name": "Telegram",
  53 + "description": "",
  54 + "item": []
  55 + },
  56 + {
  57 + "name": "Application appearing",
  58 + "request": {
  59 + "url": "localhost:8080/bht-chatbot ",
  60 + "method": "GET",
  61 + "header": [],
  62 + "body": {},
  63 + "description": ""
  64 + },
  65 + "response": []
  66 + }
  67 + ]
  68 +}
0 \ No newline at end of file 69 \ No newline at end of file