installation-development.md

# Install for Development

<!-- TOC -->

- [Install for Development](#install-for-development)
    - [Prerequisites](#prerequisites)
    - [Setup Database](#setup-database)
    - [Installation](#installation)
    - [Configuration](#configuration)
    - [Running Engine](#running-engine)
    - [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:

```bash
sudo apt-get install \
    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
```

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

## Setup Database

The following installation script sets up the database.

```bash
  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.

In case of MariaDB the script also installs these system dependencies:

  apt-get install mariadb-server libmariadbclient-dev

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.

**Cloning the project**

Then clone the project to some development folder:

```bash
git clone https://gitlab.servus.at/autoradio/engine
```

## Installation


```shell
./install.sh
```

This script does the following:

- Install Liquidsoap components using OPAM (`scripts/install-opam-packages`)
- NodeJS Modules (`scripts/install-web.sh`)
- Python Packages (`requirements.txt`)
- Creates a default configuration file in `config/engine.ini`

When this is completed, carefully check if any error occured.


## Configuration

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

```shell
./config/engine.ini
```

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

Set the URLs to the *Steering* and *Tank* 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/david/.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*:

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

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

Use the convencience script `run.sh` to get engine started in different ways:

**Run the Engine**

This includes the Liquidsoap audio engine, but does not start the API server.

```shell
    ./run.sh
```

**Run the Engine Core and Liquidsoap separately**

When developing and debugging engine it is helpful to start the core and the Liquidsoap
component separately. In such case it is important to start both in the correct order.

First start the core of the engine:

```shell
    ./run.sh core
```

When engine-core completed its boot phase, indicated by a log that it is waiting for 
Liquidsoap, you can run following:

```shell
    ./run.sh lqs  
```

## Logging

All Engine logs for development can be found under `./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)