installation-production.md

# Install for Production

<!-- TOC -->

- [Install for Production](#install-for-production)
    - [Prerequisites](#prerequisites)
    - [Installation](#installation)
    - [Configuration](#configuration)
    - [Running Engine](#running-engine)
        - [Running with Systemd](#running-with-systemd)
        - [Running with Supervisor](#running-with-supervisor)
    - [Logging](#logging)
    - [Read more](#read-more)

<!-- /TOC -->

## Prerequisites

Aura Engine runs on any modern Debian-based OS. It requires at least

- `Python 3.7` or `Python 3.8`
- `git`

Additionally you'll need these system packages below.

```shell
sudo apt-get update
sudo apt-get install \
    supervisor \
    opam \
    libsndfile1 \
    ffmpeg \
    quelcom \
    python3-pip \
    virtualenv \
    libssl-dev
```



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**

While previous packages need superuser rights to be installed, the following ones are installed for the user which is
executing the engine. In your development environment you can skip this step. In production you first need to create
a user called `engineuser`.

```shell
    sudo adduser engineuser
    sudo adduser engineuser audio sudo
```

And switch to that user

```shell
  su engineuser
```

**Liquidsoap Repository**

Engine requires at least `Liquidsoap 1.4.3` or newer, installed using [OPAM (OCaml Package Manager)](https://opam.ocaml.org/).

Add the current Liquidsoap repository from [this installation guide](https://www.liquidsoap.info/doc-1.4.3/install.html).

The other steps required for the Liquidsoap installation are handled by the `install.sh` script. If you experience any
errors, carefully review them and consult the official documentation for installing Liquidsoap.

**Cloning the project**

Create the folder `/opt/aura` and clone the engine project from there:

```shell
  engineuser:/opt/aura/$  git clone https://gitlab.servus.at/autoradio/engine
```

Now you should have `/opt/aura/engine/`.

Let's move inside the home of engine:

```shell
  engineuser:/opt/aura/$ cd engine
```

**Setup the database**

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 scripts/setup-db.sh
```

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**

Call this script to create the required log folders and update all permissions.

```bash
  root:/opt/aura/engine$ bash scripts/initialize.sh
```

## Installation

The following installation script also sets up the database.

By default Aura Engine uses MariaDB for persistence. When starting the installation, 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.

```shell
engineuser:/opt/aura/engine$  ./install.sh prod
```

This script does the following:

- Install Liquidsoap components using OPAM (`scripts/install-opam-packages`)
- Python Packages (`requirements.txt`)
- Creates a default Engine configuration file in `/etc/aura/engine.ini`

When this is completed, carefully check if any error occured. In case your database has been setup
automatically, note the relevant credentials for later use in your `engine.ini` configuration.

## Configuration

In your production environment edit following file to configure the engine:

```shell
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---"
```

Set the URLs to the *Steering*, *Tank* and *Engine* API:

```ini
[api]

# The URL to get the health status 
api_steering_status = "http://aura.local:8000/api/v1/"
# The URL to get the Calendar via Steering
api_steering_calendar="http://aura.local:8000/api/v1/playout"
# The URL to get show details via Steering
api_steering_show="http://aura.local:8000/api/v1/shows/${ID}/"

## TANK ##

# The URL to get the health status 
api_tank_status = "http://aura.local:8040/healthz/"
# The URL to get playlist details via Tank
api_tank_playlist="http://aura.local:8040/api/v1/playlists/${ID}"

## ENGINE-API ##

# Engine ID (1 or 2)
api_engine_number = 1
# Engine API endpoint to store playlogs
api_engine_store_playlog = "http://localhost:8008/api/v1/playlog/store"
# Engine API endpoint to store clock information
api_engine_store_clock = "http://localhost:8008/api/v1/clock"
# Engine API endpoint to store health information
api_engine_store_health = "http://localhost:8008/api/v1/source/health/${ENGINE_NUMBER}"
```

Ensure that the Liquidsoap installation path is valid:

```ini
[lqs]
liquidsoap_path="/home/engineuser/.opam/4.08.0/bin/liquidsoap"
```

**Configuring the Audio Store**

Finally Engine needs to be able to access the audio folder, where all the tracks of the playlists
are stored via *Tank*:

```ini
[audiosource]
audio_source_folder="/var/audio/source"
```

There is some document on how to [Setup the Audio Store](docs/setup-audio-store.md).

If the audio device desired for playback is set as `default`, the Engine now should be ready to play
sound. You can check the default audio hardware by executing `aplay -L` on the command line. If that's
not the case you can set the default device in `/etc/asound.conf`. More advanced audio device settings
can be looked up in the [Configuration Guide](docs/configuration-guide.md).

Read about all other available settings in the [Configuration Guide](docs/configuration-guide.md).

## Running Engine

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 you can utilize either [Systemd](https://systemd.io/) or [Supervisor](http://supervisord.org/).

### Running with Systemd

Copy the unit file `/opt/aura/engine/config/systemd/aura-engine.service` to `/etc/systemd/system/`.

This unit file starts engine-core and engine-liquidsoap within one command. Here Liquidsoap is started as
as subprocess.

> Please note not to use any other unit files in that directory yet. They are work in progress.

Now you'll need to reload the Systemd unit files

```shell
sudo systemctl daemon-reload
```

**Start**

```shell
sudo systemctl start aura-engine
```

**Stop**

```shell
sudo systemctl start aura-engine
```

**Restart**

```shell
sudo systemctl restart aura-engine
```

**Status**

```shell
sudo systemctl status aura-engine
```

### Running with Supervisor

Now, given you are in the engine's home directory `/opt/aura/engine/`, simply type following to start
the services:

```shell
supervisord
```

This picks up the supervisor configuration provided in the local `supervisord.conf` and the service configurations
located in `config/supervisor/*.conf`.

Experience has shown it might be helpful to reload the supervisor configuration using `sudo`:

```shell
sudo supervisorctl reload
```

Note that the supervisor daemon starts all (both) services at once. If you want more fine-grained control for
starting services individually, please check-out the next section.

**Listing available Services**

```shell
engineuser:/opt/aura/engine$ supervisorctl avail
```

You should get these all services with their actual state listed:

```c++
aura-engine                      in use    auto      666:666
aura-engine-api                  in use    auto      999:999
```

**Maintanence using Supervisor**

Please remember to call all `supervisorctl` commands from within your engine home directory (`/opt/aura/engine/`),
to pickup the correct `supervisord.conf`.

**Starting Services**

```shell
    supervisorctl start <service-name>
```

**Stopping Services**

```shell
    supervisorctl stop <service-name>

```

**Restarting Services**

```shell
    supervisorctl restart <service-name>
```

**Refresh after changing configurations**

```shell
    supervisorctl restart <service-name>
```

In case you want to reload whole supervisor service

```shell
    sudo service supervisor restart
```

## Logging

All Engine logs for production can be found under:

```shell
    `/var/log/aura`
```

and

```shell
    `/opt/aura/engine/logs`
```

## Read more

- [Overview](/README.md)
- [Installation for Development](installation-development.md)
- [Installation for Production](installation-production.md)
- [Running with Docker](running-docker.md)
- [Setup the Audio Store](docs/setup-audio-store.md)
- [Developer Guide](developer-guide.md)
- [Engine Features](engine-features.md)
- [Frequently Asked Questions (FAQ)](docs/frequently-asked-questions.md)