# Deployment Preparations

## Requirements

- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git/)
- [make](https://www.gnu.org/software/make/)
- [Docker Engine 25.0.2 or later](https://docs.docker.com/engine/install/)
- [Docker Compose 2.15.1 or later](https://docs.docker.com/compose/install/)

## Choose a domain name

First decide where you want AURA to be served to your users. Given your radio website is available
under `myradio.org`, we recommend binding AURA to the subdomain `dashboard.myradio.org`. Dashboard
is the application you will interact most often with, therefore it shall get a prominent place in
your URL scheme.

Update your DNS settings with your desired domain name and point it to the server instance you
want to deploy AURA at.

In all of the following examples, we will refer to the `dashboard.myradio.org` example. Replace it
with your personal AURA subdomain, where applicable.

## Setting up the user & home directory

It's time to log in to your fresh AURA server instance and get things moving.

Clone the `aura` repository to your desired AURA home directory.

We recommend using `/opt/aura` for the AURA installation.

```bash
$ sudo mkdir /opt/aura
$ sudo chown -R $(id -u):$(id -g) /opt/aura
$ git clone https://gitlab.servus.at/aura/aura.git /opt/aura
```

Next, move to that directory and create the `aura` user and group:

```bash
$ make aura-user.add
```

This is user merely required for handing out correct permissions and ownership. It is not meant
to login with.

```{admonition} Current user vs. aura user
:class: tip
All operations are meant to be done by the current user. This user is also added to the `aura`
group, hence acts on behalf of the `aura` user.

```

## Docker post-installation steps

Install _Docker Engine_ to be [managed as a non-root user](https://docs.docker.com/engine/install/linux-postinstall/).
Choose the previously created `aura` user to be in charge of running your containers.

Also, you don't need any fancy additions like _Docker Desktop_.

```{admonition} Ensure that Docker default context is enabled
:class: tip
Docker Desktop may change the current context. Switch back to the default Docker context with
`docker context use default`.
```

### Docker in production

When configuring the Docker Engine for _production_, you may want to start all your containers
automatically on system boot.

This can be achieved by [running Docker Engine as a daemon](https://docs.docker.com/config/daemon/).
We recommend using the `aura` user for running Docker Engine using `systemd`.

## Selecting the release

Ensure you have the latest codebase:

```bash
$ git pull
```

Then check for available releases:

```bash
$ git tag
   1.0.0-alpha1
   1.0.0-alpha2
   1.0.0-alpha3
```

This command returns a list of all tags corresponding to the available releases.
Alternatively you can take a look at [releases.aura.radio](https://releases.aura.radio).

To learn about changes between releases, consult the [Release Notes](../release-notes.md).

Then switch to the release you'd like to use.

```bash
$ git checkout tags/<release-version>
```

Replace `<release_version>` with one of the versions listed above, like `1.0.0-alpha1`.

```bash
$ git checkout tags/1.0.0-alpha1
```

```{admonition} Latest, unreleased state on the main branch
:class: tip
In case you want deploy the current development state, just take the latest commit on the `main`
branch. That's the state which is checked out by default. While we try to keep the `main` branch
as stable as possible, we cannot guarantee it being functional at all times. So please use it at
your own risk.
```

## Setting up the Audio Store

The _Audio Store_ is a folder which is utilized by _Tank_ and _Engine_ to exchange audio files.

Assuming both, _Engine_ and _Tank_ are hosted on different machines, audio folders must by shared
using some network share.

In case you are hosting _Engine_ and _Tank_ on the same machine, you can skip this step. Just
think about pointing the settings the relevant audio directories, or create a symlink to do
so behind the curtains.

By default the audio store is located in `/opt/aura/audio`. There are following subdirectories
expected:

- `source`: Holding all audio files from the media asset repository. Written by _Tank_ and read by _Engine_.
- `fallback`: Populate this folder with audio files to be played randomly, in cases where nothing is scheduled.
- `playlist`: Used for M3U audio playlists.
- `recordings`: The recorder stores its recorded blocks here.
- `import`: To import audio files into Tank via the filesystem, place them here.

### Share Type

Then, there's the question how the share is managed. Feasible options include:

- [NFS](https://en.wikipedia.org/wiki/Network_File_System)
- [SSHFS](https://en.wikipedia.org/wiki/SSHFS)
- [Gluster](https://www.gluster.org/)

Please evaluate for yourself what the most failsafe solution is. The next chapter outlines pro
and cons of different scenarios.

### Share Location

You have following options where your share can be located:

1. **Engine and all other AURA components (Tank, Dashboard, Steering) are running on the same instance.**
   This is the most simple solution, as Engine and Tank can share the same directory locally. But
   this scenario requires some more sophisticated tuning of the system resources to avoid e.g.
   some overload of multiple Uploads in Tank may affect the performance of engine. You can
   eliminate this risk by setting CPU and memory limits for Steering, Dashboard and Tank using
   Docker or `systemd-cgroups`. A disadvantage here is the case of maintenance of system reboot.
   This would mean that all components are offline at once.

2. **Physical directory where the Engine lives, mounted to Tank**. This may cause an issue with
   the mount, when the network connection to Engine is unavailable or the instance is rebooting.

3. **Physical directory where the Tank lives, mounted to Engine.** This may cause an issue with
   the mount, when the network connection to Tank is unavailable or the instance is rebooting.

4. **Central Data Store or _Storage Box_** which is mountet to Engine and Tank. In this case a
   downtime of the store make both, Engine and Tank dysfunctional.

5. **Replicated storage solution using [Gluster](https://www.gluster.org/), both Engine and Tank have their virtual audio directory mounted.**
   That's the ideal approach, because if any of the instances is down, the other has all the data
   available.

In any case, you should think about some backup solution involving this directory.

Learn more on how what should be backed up in the chapter
[Update and Maintain / Backup Strategy](update-and-maintain.md#backup-strategy).

## Deployment

AURA can be deployed using Docker and Docker Compose, allowing custom-tailored orchestration.

In the next chapters you learn how to deploy the individual Docker Compose bundles:

- AURA Web
- AURA Playout
- AURA Recorder