Initial version of the documentation.

README.md

@@ -2,16 +2,54 @@
 
 ## Overview
 
-The Project serves the Engine API and handles state management of multiple Engine instances.
+The Project serves the Engine API and handles state management of multiple [Engine](https://gitlab.servus.at/aura/engine) instances.
 
-This project is based on a swagger-enabled Flask server using an *API First* approach. It also uses the [Connexion](https://github.com/zalando/connexion) library on top of Flask.
+The Engine API stores and provides following information:
+
+- Playlogs: A history of all audio titles being played by the Engine. This is used for detailed reports.
+- Track Service: Same as track service, but stripped-down information. Used for implementing a track service feature on the radio's website.
+- Active Source: In redundant deployment scenarios the API stores and shares information on which engine instance is active. This could be extended to other audio sources.
+- Health Information: In case of some critical issue, the health status of the respective engine is stored.
+
+You can find details on the available API endpoints here: https://app.swaggerhub.com/apis/AURA-Engine/engine-api/1.0.0
+
+## Deployment Modes
+
+AURA Engine allows single and redundant deployments.
+
+### Single Deployment
+
+This is the most simple case. In that scenario the Engine API is deployed on the same host as the [Engine](https://gitlab.servus.at/aura/engine) itself.
+
+> In your live deployment you might not want to expose the API directly on the web. For security reasons it's highly recommended to guard it using something like a reverse proxy.
+
+<img src="docs/engine-api_single.png" width="500" />
+
+### Redundant Deployment
+
+In this scenario there are two Engine instances. Here you will need deploy one Engine API on the host of each Engine instance.
+Additionally you'll have to deploy a third, so-called "Syncronization Node" of the Engine API. The sync instanc of Engine API
+is in charge of synchronizing playlogs, health information etc.
+
+<img src="docs/engine-api_redundancy.png" width="500" />
+
+## Getting started
 
-## Requirements
+### Requirements
+
+If you are not planning to go with Docker or just want to setup a local development environment, then you'll need:
 
 Python 3.7+
-MariaDB (or similar Database)
+MariaDB
+Virtualenv
+
+### Installation
 
-## Installation
+Create a virtual environment for your Python dependencies:
+
+```bash
+virtualenv -p python3.7 python
+```
 
 Install the required dependencies:
 
@@ -23,21 +61,90 @@ pip3 install -r contrib/mariadb-requirements.txt
 sudo mysql -u root -p < contrib/mariadb-database.sql
 ```
 
-## Getting started
+### Configuration
 
-To run the server, please execute the following from the root directory:
+Copy the the sample configuration file in `./config/sample/sample-production.engine-api` to `config` and edit the file.
+First update the main configuration and then configure the type of federation. Depending on how you want to run your
+Engine API node and where it is deployed, you'll needed to uncomment one of these federation sections:
 
-```bash
-./run.sh api
+> To avoid any malfunction it is important that any other node-type configurations are commented out.
+
+#### Engine 1 Node
+
+Use this section if you are running [AURA Engine](https://gitlab.servus.at/aura/engine) standalone or if this is the first API node in a redundant deployment.
+
+Replace `localhost` and port number with the actual details of your sync node.
+
+```ini
+# NODE 1
+host_id=1
+sync_host="http://localhost:8010"
 ```
 
+#### Engine 2 Node
+
+In case this is the second API node in a redundant deployment.
+
+Replace `localhost` and port number with the actual details of your sync node.
+
+```ini
+# NODE 2
+host_id=2
+sync_host="http://localhost:8010"
+```
+
+#### Synchronization Node
+
+This is the synchronization instance in a redundant setup. This instance combines all valid information from coming from Engine API 1 and 2.
+
+Replace `localhost` and port number with the actual details of your main nodes.
+
+```ini
+# NODE SYNC
+host_id=0
+main_host_1="http://localhost:8008"
+main_host_2="http://localhost:8009"
+default_source=1
+sync_interval=3600
+sync_batch_size=100
+sync_step_sleep=0.23
+```
+
+## Running the Server
+
+### Development
+
 To run the API in an local development server execute:
 
 ```bash
 ./run.sh api-dev
 ```
 
-## Running with Docker
+For convenience running a plain `./run.sh` also starts the development server.
+
+When you'll need to run all three nodes to do testing during development you can run:
+
+```bash
+./run.sh api-test-0 # Sync Node
+./run.sh api-test-1 # Node 1
+./run.sh api-test-2 # Node 2
+```
+
+Here the run script uses the configurations located in `./test/config`.
+
+### Production
+
+To run the server for production using Gunicorn, you first need to create the Gunicorn configuration
+by copying the sample `./config/sample/gunicorn/sample-production.gunicorn.conf.py`
+to your `config` directory.
+
+Then run this from the root directory:
+
+```bash
+./run.sh api
+```
+
+### Running with Docker
 
 To run the server on a Docker container, please execute the following from the root directory:
 
@@ -54,6 +161,8 @@ To run the server on a Docker container, please execute the following from the r
 
 ## Using the API
 
+You can find details on the available API endpoints here: https://app.swaggerhub.com/apis/AURA-Engine/engine-api/1.0.0
+
 Adding some entry to the playlog:
 
 ```bash
@@ -93,3 +202,7 @@ sudo pip install tox
 ```
 
 > Note, the test-cases are currently not functional.
+
+# About
+
+This project is based on a swagger-enabled Flask server using an *API First* approach. It also uses the [Connexion](https://github.com/zalando/connexion) library on top of Flask.