AURA Web

For all of the following steps, please change to /opt/aura, also referenced as $AURA_HOME.

Quick Installation Guide

Deployment preparation steps:

$ git pull
$ git tag
    1.0.0-alpha1
    1.0.0-alpha2
    1.0.0-alpha3
$ git checkout tags/<release-version>
$ make aura-user.add
$ make aura-web.init

Modify the newly created configuration file and initialize the database:

$ nano config/aura-web/.env
$ make aura-web.configure

Now create fixtures based on samples, edit or delete files. Then import fixtures as the last step:

$ make aura-web.fixtures-create
$ nano config/aura-web/fixtures/...
$ make aura-web.fixtures-import

After this is set, start AURA Web with:

$ make aura-web.up

Watch the health status and logs with:

aura$ docker ps
aura/config/aura-web$ docker compose logs -f

For additional maintenance options, see Update and Maintenance.

Complete Installation Guide

Call following command to initialize the Aura Web environment:

$ make aura-web.init

This command does

  • create a configuration file .env, based on the sample configuration sample.env located in config/aura-web.

  • update the ownership and permissions of relevant files and folders.

  • create a set of sample fixtures located in config/aura-web/fixtures. It’s up to you, if you want to use them.

Modify the configuration file

The previous step already created a .env file based on sample.env.

Now let’s configure the essentials.

Configure host and certificate generation

Now you need to configure how AURA is reachable.

Environment variable

Values (default)

Description

AURA_HOST_NAME

Set a LAN host or a domain name. See below why to avoid localhost.

AURA_HOST_PROTO

https, http

Defaults to https. Set to http if you are running locally.

AURA_HOST_CERTBOT_ENABLE

true, false

Set to false if you are running locally or retrieve certificates differently.

AURA_HOST_CERTBOT_EMAIL

Set a valid email for certbot.

By default it is meant to be reached via a publicly facing domain name. AURA by default offers automatic generation of TLS certificates using certbot.

Therefore you only need to set the values for AURA_HOST_NAME and AURA_HOST_CERTBOT_EMAIL.

Ensure you use a fully qualified domain name, like dashboard.myradio.org, and that your firewall allows outside connections from port 80 as well.

Changing the host

Any update of host and protocol in your .env file later on, is not reflected in the actual configuration. In such cases you either need to manually update the relevant OIDC client database tables, or you simple create new OIDC client IDs in the configuration. After that you can delete any old OIDC clients via the Steering admin interface /steering/admin/oidc_provider/. Read more about this in the Update & Maintain section.

Local deployment

When deploying AURA locally, you can choose a LAN hostname. For example you can define aura.local in /etc/hosts. Then set this value for AURA_HOST_NAME. Also ensure you use http as protocol and to disable certbot.

Avoid using localhost and 127.0.0.1

Since the hostname localhost and the IP 127.0.0.1 is ambiguous when using Docker, ensure to avoid these in your configuration altogether. Otherwise this will result in a dysfunctional installation.

Configure connectivity to other services

Depending on your infrastructure setup, also set these environment variables:

Environment variable

Description

AURA_AUDIO_STORE_SOURCE

Tank stores audio files here. It defaults to aura/audio/source.

AURA_TANK_ENGINE_PASSWORD

Choose a password and remember it for configuring AURA Playout.

AURA_ENGINE_API_INTERNAL_URL

Set URL if AURA Playout is deployed to another host.

Apply the database configuration

To initialize the database based on the configuration file, call the following:

$ make aura-web.configure

This step will

  • Create the database by running the migrations,

  • Create the RSA Key

  • Create the OpenID Connect clients for dashboard and tank,

  • Create a super user.

Import default radio station metadata

The radio station metadata settings can be imported using so-called fixtures. Fixtures hold a set of default or sample data, which can be imported, avoiding manual creation of certain records.

To create a set of fixtures based on sample data call:

$ make aura-web.fixtures-create

This creates a set fixtures in config/aura-web/fixtures based on the samples provided in config/aura-web/fixtures/sample. Note that any existing file are overwritten.

The following table gives an overview on fixture types and their use.

File

Required

Description

category.json

Metadata to categorize shows with.

fundingcategory.json

✅

Metadata for reporting on shows. Required for creating new shows.

host.json

Allows creation of a default host, assigned to a default show.

language.json

Supported languages assigned to shows or episodes.

license.json

✅

Supported licenses used for image or media uploads.

linktype.json

Types of links available for shows, episodes or host profiles.

musicfocus.json

Music genres for classifying music shows.

radiosettings.json

Basic radio station configuration.

rrule.json

✅

Recurrence rules used in planning of the radio station calendar.

show.json

Allows creation of a default show, like for filling empty timeslots.

topic.json

Metadata for grouping shows and episodes per certain topics.

type.json

✅

Metadata for grouping shows per content format. Required for creating new shows.

Edit or delete individual files, depending on your needs. Most types of fixtures can be skipped, but there are certain required ones, needed for a functional user interface. If you only want to give AURA a try and have some starting points, it makes sense to import all data, as is.

After reviewing and adapting fixtures to your radio station needs, execute following command to import them to the database:

$ make aura-web.fixtures-import

Add and edit metadata via administration user interface.

Do not worry if you forgot to define some default records. You can also add and modify these metadata records in the Radio Station Administration.

Start the services with Docker Compose

To start all services defined in the docker-compose.yml file, run:

$ make aura-web.up

Containers which are not yet existing are created. If some container is already running and is changed in some way, Docker Compose re-creates it.

This deployment will make AURA Web reachable in the following way:

Service

URL

Description

Dashboard

/

Dashboard is reachable directly $AURA_HOST_NAME.

Steering

/steering

Steering holds all the programme data.

Tank

/tank

Tank is the uploader or audio repository.

Track Service API

/engine/api/v1/trackservice

Track Service API is only available when engine-api is running.

Icecast

:8000/icecast

Available when optional Icecast server for the reverse proxy is enabled.

Dashboard Clock

/clock

Only available in LAN and when enabled in reverse proxy config.

Advanced configuration (LDAP and others)

If you need to extend the settings for production beyond what is possible with environment variables, you will need to create an additional configuration file for Steering. First copy the the provided sample configuration to the services folder:

$ cp config/services/sample-config/steering.py config/services/

Also compare the chapter on Advanced Configuration

Configuring LDAP

TODO: Explain LDAP Configuration, see https://gitlab.servus.at/aura/aura/-/issues/289

Start with advanced configuration

At the moment you cannot use the usual make aura-web.up to start with advanced configuration. Instead you need to use the following command:

$ config/aura-web/$ docker compose -f docker-compose.yml -f steering-production.yml up -d

This behaviour will be simplified in a coming release.