installation-production.md

Install for Production

• Install for Production
  • Prerequisites
  • Installation
  • Configuration
  • Running Engine
  • The API Server
  • Maintanence using Supervisor
  • Logging
  • Read more

Prerequisites

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

• Python 3.7
• git

Additionally you'll need these system packages below.

sudo apt-get update
sudo apt-get install \
    supervisor \
    opam \
    redis-server \
    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:

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.

    sudo adduser engineuser
    sudo adduser engineuser audio sudo

And switch to that user

  su engineuser

Liquidsoap Repository

Engine requires at least Liquidsoap 1.4.1 or newer, installed using OPAM (OCaml Package Manager).

Add the current Liquidsoap repository from this installation guide.

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:

  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:

  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.

  root:/opt/aura/engine/$ bash script/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.

  root:/opt/aura/engine$ bash script/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.

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

This script does the following:

• Install Liquidsoap components using OPAM (script/install-opam-packages)
• Python Packages (requirements.txt)
• Creates a default Engine configuration file in /etc/aura/engine.ini
• Creates a default Gunicorn configuration file in gunicorn.conf.py

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:

engineuser:/opt/aura/engine$ nano /etc/aura/engine.ini

Now, specify at least following settings to get started:

    [database]
    db_user="aura"
    db_name="aura_engine"
    db_pass="---SECRET--PASSWORD---"

Set the URLs to the Steering and Tank API:

[api]

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

# TANK
api_tank_status = "http://localhost:8040/healthz"
# The URL to get playlist details via Tank
api_tank_playlist="http://localhost:8040/api/v1/shows/${SLUG}/playlists"

Ensure that the Liquidsoap installation path is valid:

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

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

[audiofolder]
audiofolder="/var/audio"

There is some document on how to Setup the Audio Store.

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.

Read about all other available settings in the Configuration Guide.

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 we utilize Supervisor.

Also note, while running the engine might also work using a systemd service, the recommened option to use in combination with Gunicorn (API server, see below), 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:

supervisord

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

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

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

engineuser:/opt/aura/engine$ supervisorctl avail

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

aura-engine                      in use    auto      666:666
aura-engine-api                  in use    auto      999:999

The API Server

For production Engine API uses the WSGI HTTP Server Gunicorn.

In production Gunicorn is used in combination with some proxy server, such as Nginx.

Although there are many HTTP proxies available, we strongly advise that you use Nginx. If you choose another proxy server you need to make sure that it buffers slow clients when you use default Gunicorn workers. Without this buffering Gunicorn will be easily susceptible to denial-of-service attacks. You can use Hey to check if your proxy is behaving properly. — Gunicorn Docs.

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

    supervisorctl start <service-name>

Stopping Services

    supervisorctl stop <service-name>

Restarting Services

    supervisorctl restart <service-name>

Refresh after changing configurations

    supervisorctl restart <service-name>

Start the API service with Supervisor

    sudo supervisorctl update
    sudo supervisorctl restart engine-api

In case you want to reload whole supervisor service

    sudo service supervisor restart

Logging

All Engine logs for production can be found under:

    `/var/log/aura`

This includes individual logs from Engine Core, Liquidsoap and the API. But also stdout outputs from supervisor services are written there.

Additionally you'll finde Supervisor specific logs under:

    `/var/log/supervisor`

Read more

• Overview
• Installation for Development
• Installation for Production
• Running with Docker
• Setup the Audio Store
• Configuration Guide
• Developer Guide
• Engine Features
• Frequently Asked Questions (FAQ)