Improved documentation.

docs/installation-development.md

@@ -24,14 +24,26 @@ Aura Engine runs on any modern Debian-based OS. It requires at least
 Additionally you'll need these system packages:
 
 ```bash
-apt-get install \
+sudo apt-get install \
     opam \
     redis-server \
     libsndfile1 \
     ffmpeg \
     quelcom \
+    python3-pip
 ```
 
+Depending on the database management system you gonna use, you'll also need to install those packages. 
+
+In case of MariaDB this is:
+
+```shell
+sudo apt-get install \
+    python-dev \
+    default-libmysqlclient-dev \
+    mariadb-server \
+    libmariadbclient-dev
+```
 
 **Install Liquidsoap**
 
@@ -101,6 +113,15 @@ In your development environment edit following file to configure the engine:
 Please note if some configuration exists under `/etc/aura/engine.ini` the configuration is
 read from there by default.
 
+Now, specify at least following settings to get started:
+
+```ini
+  [database]
+  db_user="aura"
+  db_name="aura_engine"
+  db_pass="---SECRET--PASSWORD---"
+```
+
 Read more about detailed settings in the [Configuration Guide](docs/configuration-guide.md).
 
 ## Running Engine

docs/installation-production.md

@@ -23,14 +23,28 @@ Aura Engine runs on any modern Debian-based OS. It requires at least
 
 Additionally you'll need these system packages:
 
-```bash
-apt-get install \
+```shell
+sudo apt-get install \
     supervisor \
     opam \
     redis-server \
     libsndfile1 \
     ffmpeg \
     quelcom \
+    python3-pip \
+    virtualenv
+```
+
+Depending on the database management system you gonna use, you'll also need to install those packages.
+
+In case of MariaDB this is:
+
+```shell
+sudo apt-get install \
+    python-dev \
+    default-libmysqlclient-dev \
+    mariadb-server \
+    libmariadbclient-dev
 ```
 
 **Create an user**
@@ -39,61 +53,74 @@ While previous packages need superuser rights to be installed, the following one
 executing the engine. In your development environment you can skip this step. In production you first need to create
 a user called `engineuser`.
 
-```bash
-    adduser engineuser
-    adduser engineuser audio
+```shell
+    sudo adduser engineuser
+    sudo adduser engineuser audio sudo
 ```
 
 And switch to that user
 
-```bash
+```shell
   su engineuser
 ```
 
 **Install Liquidsoap**
 
-Now it's time to install the Liquidsoap and its dependencies.
-
-Install `Liquidsoap 1.4.1` or newer, using [OPAM (OCaml Package Manager)](https://opam.ocaml.org/).
+Install at least `Liquidsoap 1.4.1` or newer, using [OPAM (OCaml Package Manager)](https://opam.ocaml.org/).
 
-Follow this installation guide: https://www.liquidsoap.info/doc-1.4.1/install.html
+Follow [this installation guide](https://www.liquidsoap.info/doc-1.4.1/install.html) or the summarized steps below.
 
-Let's initialize OPAM for the user you are going to run the engine with:
+1. Let's initialize OPAM for the user you are going to run the engine with:
 
-```bash
-  engineuser:$  opam init
+```shell
+  engineuser:$  opam init -y
 ```
 
+2. Ensure to have at least the OCaml version v4.08.0
+
+```shell
+  engineuser:$  opam switch create 4.08.0
+```
 
-**Setup Database**
+3. Update the current shell environment
 
-The following installation script sets up the database.
 
-```bash
-  bash script/setup-db.sh
+```shell
+  engineuser:$  eval $(opam env)
 ```
 
-By default Aura Engine uses MariaDB for persistence. When starting this script, please
-ensure you have root access to your database instance. The installation script automatically
-creates a database plus an associated user with password. If you want to use your own database
-system, select "Other / Manually" during the database installation step.
 
-In case of MariaDB the script also installs these system dependencies:
+**Cloning the project**
 
-  apt-get install mariadb-server libmariadbclient-dev
+Create the folder `/opt/aura` and clone the engine project from there:
 
-If you have chosen to setup your database automatically, note the relevant credentials.
+```shell
+  engineuser:/opt/aura/$  git clone https://gitlab.servus.at/autoradio/engine
+```
 
+Now you should have `/opt/aura/engine/`.
 
-**Cloning the project**
+Let's move inside the home of engine:
+
+```shell
+  engineuser:/opt/aura/$ cd engine
+```
 
-Create the folder `/opt/aura` and clone the engine project:
+**Setup the database**
 
-```bash
-git clone https://gitlab.servus.at/autoradio/engine
+The following installation script sets up the database. You either need to be logged in as root
+or have sudo rights.
+
+```shell
+  root:/opt/aura/engine/$ bash script/setup-db.sh
 ```
 
-Now you should have `/opt/aura/engine/`.
+By default Aura Engine uses MariaDB for persistence. When starting this script, please
+ensure you have root access to your database instance. The installation script automatically
+creates a database plus an associated user with password. If you want to use your own database
+system, select "Other / Manually" during the database installation step.
+
+If you have chosen to setup your database automatically, note the relevant credentials.
 
 
 **Initialize folders and permissions**
@@ -101,7 +128,7 @@ Now you should have `/opt/aura/engine/`.
 Call this script to create the required log folders and update all permissions.
 
 ```bash
-  bash script/initialize.sh
+  root:/opt/aura/engine$ bash script/initialize.sh
 ```
 
 ## Installation
@@ -114,15 +141,13 @@ creates a database plus an associated user with password. If you want to use you
 system, select "Other / Manually" during the database installation step.
 
 ```shell
-./install.sh prod
+engineuser:/opt/aura/engine$  ./install.sh prod
 ```
 
 This script does the following:
 
 - Install Liquidsoap components using OPAM (`script/install-opam-packages`)
-- NodeJS Modules (`script/install-web.sh`)
 - Python Packages (`requirements.txt`)
-- Creates a log folder in `/var/log/aura/`
 - Creates a default Engine configuration file in `/etc/aura/engine.ini`
 - Creates a default Gunicorn configuration file in `gunicorn.conf.py`
 
@@ -134,19 +159,32 @@ automatically, note the relevant credentials for later use in your `engine.ini`
 In your production environment edit following file to configure the engine:
 
 ```shell
-nano /etc/aura/engine.ini
+engineuser:/opt/aura/engine$ nano /etc/aura/engine.ini
+```
+
+Now, specify at least following settings to get started:
+
+```ini
+    [database]
+    db_user="aura"
+    db_name="aura_engine"
+    db_pass="---SECRET--PASSWORD---"
 ```
 
 Read more about detailed settings in the [Configuration Guide](docs/configuration-guide.md).
 
 ## Running Engine
 
-In production the process of starting the engine is slightly different to ensure the engine's components
-are always running i.e. restart themselves after some system restart or crash. Therefore they are executed
-using [Supervisor](http://supervisord.org/). While running might also work using a `systemd` service, the
+In production the process of starting the engine is slightly different compared to some development environment.
+This is due to the need of ensuring the engine's components are always running i.e. letting them to restart
+automatically after some system restart or crash has happened.
+
+For this we utilize [Supervisor](http://supervisord.org/).
+
+Also note, while running the engine might also work using a `systemd` service, the
 recommened option to use in combination with Gunicorn ([API server](Running the API Server), see below),
-is Supervisor. Beside others, Supervisor has the advantage that you are able to run services without 
-being superuser.
+is Supervisor. Beside others pros, Supervisor has the advantage that you are able to run services without
+having superuser rights.
 
 Now, given you are in the engine's home directory `/opt/aura/engine/`, simply type following to start
 the services:
@@ -164,7 +202,7 @@ starting services individually, please check-out the next section.
 **Listing available Services**
 
 ```shell
-    supervisorctl avail
+engineuser:/opt/aura/engine$ supervisorctl avail
 ```
 
 You should get these two services with their actual state listed: