# AURA Web

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

## Quick Installation Guide

[Deployment preparation steps](deployment-preparation.md):

```bash
$ 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](#modify-the-configuration-file) and initialize the
database:

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

Now create [fixtures](#import-default-radio-station-metadata) based on samples, edit or delete
files. Then import fixtures as the last step:

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

After this is set, start AURA Web with:

```bash
$ make aura-web.up
```

Watch the health status and logs with:

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

For additional maintenance options, see [Update and Maintenance](update-and-maintain.md).

## Complete Installation Guide

Call following command to initialize the Aura Web environment:

```bash
$ 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](https://certbot.eff.org/).

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.

```{admonition} Changing the host
:class: alert

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](update-and-maintain.md#create-openid-connect-clients).
```

##### 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_.

```{admonition} Avoid using localhost and 127.0.0.1
:class: alert

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:

```bash
$ 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:

```bash
$ 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:

```bash
$ make aura-web.fixtures-import
```

```{admonition} Add and edit metadata via administration user interface.
:class: tip

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](../user/admin/index.md).
```

### Start the services with Docker Compose

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

```bash
$ 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:

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

Also compare the chapter on [Advanced Configuration](advanced-config.md)

#### 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:

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

This behaviour will be simplified in a coming release.