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.
`nats`	✅	Message broker for internal communication between services.
`can`	✅	Proxy for web-based NATS communication.
`battery`	✅	Service container for various tasks (media asset management, audio processing, background jobs).
`dashboard`	✅	Backend user interface.
`dashboard-clock`		Studio clock.

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

Optionally, you can provide custom paths for the audio store and logs directory by passing AURA_AUDIO_STORE and AURA_LOGS as arguments:

make aura-web.init AURA_AUDIO_STORE=/path/to/audio AURA_LOGS=/path/to/logs

This command does the following:

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 to `localhost` or a domain name. See below for the necessary adjustments with `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 on localhost you need to add the docker-compose.localhost.yml file to the COMPOSE_FILE-var in the .env. This also needs to be done for aura-playout.

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 secrets and connections to other services

You can use openssl rand -hex 16 to generate values for variables needing secrets or tokens.

Environment variable	Description
`AURA_PLAYOUT_HOST`	Set hostname or IP, only if AURA Playout is deployed to another host.
`AURA_AUDIO_STORE_UPLOAD`	Audio files are stored here. It defaults to `aura/audio/upload`.
`AURA_NATS_API_TOKEN`	API token for the NATS service.
`AURA_BATTERY_SECRET_KEY`	Secret key for the battery service.
`AURA_BATTERY_DB_PASS`	Password for the battery service database.
`AURA_BATTERY_OIDC_CLIENT_SECRET`	Secret to authenticate against the OIDC provider.
`AURA_BATTERY_MEDIA_STORE_STEERING_TOKEN`	Secret for the media store to authenticate against steering.
`AURA_DASHBOARD_CLOCK_BATTERY_TOKEN`	Secret for the dashboard clock to authenticate against battery.
`AURA_ENGINE_BATTERY_TOKEN`	Secret for the aura engine to authenticate against battery.

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 battery,
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.

Use the required language-code object format

Ensure all translatable fields in fixtures use the required language-code object format (e.g., "name": {"de": "Lokalbezug"}). Providing a plain string instead of this structure results in corrupted records that will break the Admin UI and API endpoints.

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.
Battery	`/battery`	Battery service container for media management and various background tasks.
Engine	`/engine`	Engine API, only available when `engine-api` is running.

Optional settings

File conversion and normalization

When importing audio files to the media store, by default the original files are kept as is.

You have the option to convert to a common format and normalize audio files using loudnorm.

# Uncomment the following if you want to enable audio file conversion
# AURA_BATTERY_MEDIA_STORE_AUDIO_CONVERT_SKIP=false

# Uncomment the following if you want to enable audio normalization
# AURA_BATTERY_MEDIA_STORE_AUDIO_NORMALIZE_SKIP=false

By default, normalizing is done using the FFmpeg normalize preset podcast. When file conversion is enabled, you can set the allowed formats and the fallback format. The default fallback format is flac.

BATTERY_MEDIA_STORE_AUDIO_NORMALIZE_PRESET=podcast
BATTERY_MEDIA_STORE_AUDIO_FALLBACK_FORMAT=flac
BATTERY_MEDIA_STORE_AUDIO_ALLOWED_FORMATS=opus,flac,mp3,vorbis

Cut-Glue specific settings

The cut-glue cropping agent, which is part of battery, creates episode recordings from the block recordings created by aura-recorder. The default settings should work out of the box with aura-recorder’s default settings.

cut-glue’s default file format is FLAC. You have the option to change it:

AURA_BATTERY_CUT_GLUE_FILE_FORMAT="flac"

If you change the aura-recorder file format to something else then FLAC, make sure to update cut-glue’s option too:

AURA_ENGINE_RECORDER_FILE_FORMAT="flac"

If you change aura-recorders segment length, it is important to do the same for cut-glue:

AURA_ENGINE_RECORDER_SEGMENT_LENGTH=3600

Configuring LDAP

LDAP authentication can be configured using the following environment variables:

Environment variable	Description
`AURA_STEERING_AUTH_LDAP_ENABLE`	Set `true` to enable LDAP authentication.
`AURA_STEERING_AUTH_LDAP_ALWAYS_UPDATE_USER`	Update User objects every time the user logs in. Defaults to `true`.
`AURA_STEERING_AUTH_LDAP_BIND_DN`	Distinguished name to use when binding to the LDAP server. E.g. `cn=reader,dc=aura,dc=radio`.
`AURA_STEERING_AUTH_LDAP_BIND_PASSWORD`	Password to be used with the distinguished name.
`AURA_STEERING_AUTH_LDAP_FIND_GROUP_PERMS`	Match LDAP group names and assign permissions based on the Django group permissions. Defaults to `true`.
`AURA_STEERING_AUTH_LDAP_GROUP_SEARCH_BASE_DN`	Distinguished name of the search base for groups. E.g. `ou=groups,dc=aura,dc=radio`.
`AURA_STEERING_AUTH_LDAP_GROUP_SEARCH_SCOPE`	Scope of the search for groups. Defaults to `2` (`ldap.SCOPE_SUBTREE`).
`AURA_STEERING_AUTH_LDAP_GROUP_SEARCH_FILTER_STR`	Filter string for the group search. Defaults to `(objectClass=posixGroup)`.
`AURA_STEERING_AUTH_LDAP_MIRROR_GROUPS`	Mirror the user’s LDAP group membership in the Django database. Defaults to `true`.
`AURA_STEERING_AUTH_LDAP_SERVER_URI`	The URI of the LDAP server. E.g. `ldap://ldap.aura.radio`.
`AURA_STEERING_AUTH_LDAP_USER_ATTR_MAP`	Mapping from User attributes to LDAP attributes. E.g. `{"first_name": "givenName", "last_name": "sn", "email": "mail"}`.
`AURA_STEERING_AUTH_LDAP_USER_DN_TEMPLATE`	Template that describes any user’s distinguished name based on the user name. E.g. `uid=%(user)s,ou=people,dc=aura,dc=radio`.
`AURA_STEERING_AUTH_LDAP_USER_FLAGS_BY_GROUP`	Mapping from User flags to LDAP groups E.g. `{"is_staff": "cn=Show,ou=groups,dc=aura,dc=radio", "is_superuser": "cn=Admin,ou=groups,dc=aura,dc=radio"}`.

The environment variables default to an empty string where a default value is not listed above.

LDAP authentication via email

In order to provide email authentication, configure LDAP similar to the following example.

Note, users need to sign-in with their full email address, the email handle is not sufficient.

AUTH_LDAP_USER_DN_TEMPLATE = None
AUTH_LDAP_USER_SEARCH = LDAPSearch(
    base_dn="ou=users,dc=aura,dc=local",
    scope=2,
    filterstr="(mail=%(user)s)",
)

Mapping LDAP groups to Django group using group mirroring

When group mirroring is enabled, users signing in via LDAP are automatically assigned to a Django Group based on their LDAP group membership.

For example, if a user belongs to the LDAP group team, they are assigned to the Django Group named team. To automatically grant all members of an LDAP group the Program Manager role, and avoiding to change the actual LDAP directory structure, rename the default Django Group from Program Manager to team. Upon their next login, these users will inherit all permissions associated with that group.

Alternatively you can also clone the group Program Manager and into a new group named team.

Learn more on groups and permissions under User Guide > Radio station administration.

Advanced configuration

If you need to extend the settings beyond what is possible with environment variables, you need to create a configuration file. This is usually only needed for edge cases or developer environments.

For example, when you need to override the default Steering settings, copy the provided sample configuration to the services folder:

cp config/services/sample-config/steering_settings.py config/services/

Then, edit the files to fit your needs.

Also compare the chapter on Advanced Configuration

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