AURA Web

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

It is possible to use any directory of your choice for AURA_HOME though.

Quick Installation Guide

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

If needed, modify the newly created configuration file and then 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:

docker ps
cd 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 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 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.