Installation manual

Before proceeding, make sure to follow the preparation steps.

Services of deployment bundle

The Docker Compose bundle is holding the following set of services.

Service	Required	Description
steering	✅	Single-source of truth, holding all radio, show, user and scheduling data
tank	✅	Upload, download, normalization and media asset management
dashboard	✅	Backend user interface
dashboard-clock		Studio clock
play		A library for building frontends based on web components

The required services are needed for minimal functionality.

Initialize the deployment bundle

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. These files allow you to initialize the database with a set of default data. Their use is optional and is explained in the section Import initial radio station data below.

• create default permission assignments for the Host, Host+ and Program Manager user groups. Learn more about these roles and their default permissions under User guide > radio station administration > roles & permissions.

Modify the configuration file

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

Now let’s configure the essentials.

Configure the base URL

Now, you need to configure how AURA is reachable. The base URL is the public URL your installation will be accessible from.

The values for protocol and host name are be combined to form the base URL. For example “https://aura.myradio.org” for production or “http://aura.local” for local deployment.

Environment variable	Values (default)	Description
AURA_HOST_PROTO	http, https	Defaults to http. Set to https if you are running in production.
AURA_HOST_NAME		Set a LAN host or a domain name. See below why to avoid localhost.

Changing the host after initial configuration

Any update of the protocol and host 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.

Deployment on local machine

When deploying AURA locally, you can choose a LAN hostname. For example you can define aura.local in /etc/hosts. The matching host name has to be set for AURA_HOST_NAME.

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 Let’s Encrypt certificate generation

When you want to expose your instance directly to the web, we provide a automatic Let’s Encrypt certificate generation through certbot.

This feature is disabled by default. When enabling ensure your base URL contains a fully qualified domain name, like https://aura.myradio.org. Also check that your firewall allows inbound connections from port 80 as well.

Environment variable	Values (default)	Description
AURA_HOST_CERTBOT_ENABLE	false, true	Set to true when exposing the instance to the web and need a certificate.
AURA_HOST_CERTBOT_EMAIL		Set a valid email to retrieve certificate renewal notifications.

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 initial radio station data

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.
profile.json		Allows creation of a default profile, 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 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.
Dashboard Clock	/clock	Studio clock, only available in LAN.
Steering	/steering	Steering holds all the program data.
Tank	/tank	Tank is the uploader or audio repository.
Engine	/engine	Engine API, only available when engine-api is running.

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.