Add documentation for Adminer

Benjamin Rühl
1 parent b295b481
Showing 4 changed files with 36 additions and 1 deletions
README.md
docu/adminer.md
docu/img/persistence/adminer-login.png
docu/img/persistence/adminer-overview.png
@@ -10,7 +10,7 @@ BeuthBot is a master project of the Beuth University of Applied Sciences Berlin.
 - [Docker configuration](#docker-configuration)
 - [Local tunnel](#local-tunnel)
 - [Debug application](#debugging)
-- [Deploy application](#aeploy-application)
+- [Deploy application](#deploy-application)
 - [Known issues](#known-issues)
 - [Used online sources](#used-online-sources)
  
@@ -116,6 +116,7 @@ General
  
 - [infrastructure](docu/infrastructure.md) - The individual modules of the application
 - [persistence](docu/persistence.md) - DAOs, Entities, Hibernate, PostgreSQL
+- [adminer](docu/adminer.md) - Database management web app
  
 Individual modules
  
+# Adminer - database management web app
+
+[Adminer](https://www.adminer.org/en/) can be used to connect to a database server and select, update or delete data, show table structures, indexes, forgeign keys or triggers and much more. It is similar to `phpMyAdmin` in its intent and usage.
+
+In this project it is running in a separate docker container that is not mandatory to run but brings advantages when debugging the chat bot application.
+
+## Setup
+
+To start Adminer along with the project the [docker-compose.yml](../docker/docker-compose.yml) file has to contain the following:
+
+```
+adminer:
+    container_name: adminer_dbmanagement
+    image: adminer
+    ports:
+      - "8081:8080"
+```
+
+If the database server's ports are opened using the `expose` keyword instead of `ports`, the Adminer container needs an additional `link` to the database server container.
+The Adminer container can be left out completely when deploying to the production server.
+
+When the Adminer container is started along with the project, it should be hosted on `http://localhost:8081`. Entering this in a web browser opens the web interface asking for credentials. To connect to the PostgreSQL database choose `PostgreSQL` as database type. Database name, username and password are found in the [docker-compose.yml](../docker/docker-compose.yml) file where they are defined as `POSTGRES_DB`, `POSTGRES_USER` and `POSTGRES_PASSWORD`. The database server is the PostgreSQL database docker container which can be referenced using the container name and its port.
+
+See the following screenshot as an example:
+
+![Adminer successful login](img/persistence/adminer-login.png)
+
+## Usage
+
+Once logged in, the database schema can be seen. It should not be modified though, because it is generated by Hibernate and changes will be lost on the shutdown of the container. Clicking on a table name and selecting `select data` shows the currently persisted entities.
+
+Please note that when debugging and going step by step through the application code, changes made to the entities might not be visible in Adminer directly. The reason for this is that Hibernate starts to send changes to the database when a session is commited which is not necessarily the case when an entity is updated.
+
+![Adminer overview](img/persistence/adminer-overview.png)
 \ No newline at end of file