README.md

Aura Engine

AURA Engine is a scheduling service to control the playout of Engine Core.

This documentation is primarily meant for developers. For using the AURA Community Radio Suite check out the documentation at docs.aura.radio

To learn more about Automated Radio go to aura.radio.

Overview

The following diagram gives an simplified overview on the architecture.

flowchart LR

    api-- GET calendar -->steering[Steering API]
    api-- GET playlist -->tank[Tank API]
    ea[Engine API]
    events-- on_boot\non_sick\non_resurrect -->monitor[Monitor]
    events-- on_play\non_fallback_active -->clock[Clock]
    clock-- POST clock_data -->ea
    monitor-- PING heartbeat -->monserver[Monitoring Server]
    monitor-- POST health_data -->ea
    mixer-- UNIX SOCKET -->engine_core

    subgraph external
        ea
        monserver
        engine_core
        steering
        tank
        db[(PostgreSQL DB)]
    end
    subgraph engine
        engine_instance[Engine]-.-oplayer & events & scheduler

        scheduler-- control\ncommand\ntimer -->player[Player]

        player-- control action -->mixer
        events[Event Dispatcher *]

        subgraph scheduling
            api[Fetch & Cache API]
            timetable<-->api
            timetable<-->db
            scheduler<-->timetable[Timetable Management ***]
            scheduler-- cycle -->scheduler
        end
        subgraph core[core]
            mixer[Mixer]
        end
        subgraph plugins
            clock
            monitor
        end
    end

    style external fill:#FFF
    style ea fill:#FFF,stroke:#333,stroke-width:1px
    style steering fill:#FFF,stroke:#333,stroke-width:1px
    style tank fill:#FFF,stroke:#333,stroke-width:1px
    style monserver fill:#FFF,stroke:#333,stroke-width:1px
    style engine_core fill:#FFF,stroke:#333,stroke-width:1px

• Event Dispatcher: Events are issued and consumed in multiple locations of Engine. The diagram shows only a few ones, in order to support the overview.
• Timetable Management: Currently a database is used for caching and high-availability purposes. This is subject to changes in subsequent releases.

Prerequisites

Before you begin, ensure you have met the following requirements:

• Operating system: Debian 11, Ubuntu 20.04 or newer
• git, make
• Docker, optional if you want to run in a container
• Python 3.9+
• Poetry
• PostgreSQL 13+

Ensure that you have also dependencies such as steering, tank, dashboard, engine-core, and engine-api up and running.

Preparation

Initialize environment

Install dependencies and prepare config file:

make init.app

This also creates a default configuration file at config/engine.yaml.

For development install with:

make init.dev

Note, if some configuration exists under /etc/aura/engine.yaml the configuration by default is drawn from there. This overrides any configuration located in the local configuration file.

Initialize database

Engine requires a PostgreSQL database to cache any programme info locally.

sudo -u postgres psql -f contrib/postgresql-create-database.sql

This creates a database and tables with default password 1234.

Configuration

Edit the configuration file config/engine.yaml. Verify or change at least these config options:

# The password for the local caching database holding scheduling information
db_pass: aura-engine-dbpass
# The secret which is used to authenticate against Tank
api_tank_secret: aura-engine-secret

Running Engine

To start the Engine execute:

make run

Docker

For production deployments follow the Docker Compose installation instruction for AURA Playout at docs.aura.radio.

The following instructions are meant for development.

Build with Docker

Build your own, local Docker image

make docker.build

Run with Docker

Run the locally build image

make docker.run

Release to DockerHub

Releasing a new version to DockerHub

make docker.push

Usually this is not required, as it is done automatically by the CI/CD pipeline.

Read more

• Engine Developer Guide
• Setting up the Audio Store
• docs.aura.radio
• aura.radio