setup-audio-store.md

# Setting up the Audio Store

The *Audio Store* is a folder which is utilized by AURA Tank and Engine to exchange audio files.

Assuming AURA Engine and Tank are hosted on different machines, the `audio_source_folder` must by shared 
using some network share. 

In case you are hosting Engine and Tank on the same machine (e.g. in development), you can skip 
this documentation. Just think about pointing them to the same directory.

<!-- TOC -->

- [Setting up the Audio Store](#setting-up-the-audio-store)
    - [Share Location](#share-location)
    - [Share Type](#share-type)
    - [Setting up SSHFS](#setting-up-sshfs)
        - [Configuring Engine](#configuring-engine)
        - [Configuring Tank](#configuring-tank)
    - [Read more](#read-more)

<!-- /TOC -->

By default Engine expects audio files shared by Tank in `/var/audio/source`.

This can be configurated in `engine.ini`:

```ini
[audiosource]
audio_source_folder="/var/audio/source"
```

Now, this folder must be somehow writable by Tank.

## 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 maintainence 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 no 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 no 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.

## Share Type

Then, there's the question how the share is managed. Beside other you have the options
to use [NFS](https://en.wikipedia.org/wiki/Network_File_System), [SSHFS](https://en.wikipedia.org/wiki/SSHFS) or even something like [Gluster](https://www.gluster.org/).

For our initial setup we have chosen to use *SSHFS*.

Please share your experience with other share types, and we will include it in further releases of
this documentation.

## Setting up SSHFS

SSHFS allows you to access the filesystem on a remote computer via SSH. Interaction with files and folders behaves similar to any local data.

This example is setting up the `audio_source_folder` on the Engine instance.

### Configuring Engine

First, you'll need to create an user which enables Tank to access the `audio_source_folder` on Engine:

```shell
adduser tankuser
chown tankuser:engineuser /var/audio/source
```

Ensure that `engineuser` has no permissions to write the directory:

```shell
chmod u=+rwx,go=+rx-w /var/audio/source
```

### Configuring Tank

On the Tank side you need to install `sshfs`:

```shell
sudo apt-get install sshfs
```

Then create an `audio-store` folder inside the AURA home:

```shell
:/opt/aura/$ mkdir audio-store
```

Try if you can connect to the engine over SSH using your `tankuser`:

```shell
ssh tankuser@192.168.0.111 -p22
```

Replace `-p22` with the actual port number your SSH service is running with. For security reasons it's recommended
to run SSH not over the default port 22.

Uncomment following setting in `/etc/fuse.conf` to allow the tank-user access the share with write permissions:

```conf
# Allow non-root users to specify the allow_other or allow_root mount options.
user_allow_other
```

Now create the mount:

```shell
sudo sshfs -o allow_other -o IdentityFile=~/.ssh/id_rsa tankuser@192.168.0.111:/var/audio /opt/aura/audio-store -p22
```

Replace `192.168.0.111` with the actual IP for your Engine and `-p22` with the actual port number your Engine's SSH service
is running with.

To make this mount persistent i.e. keep it alive even after a system reboot, you'll need to add a configuration
in the `/etc/fstab` file by adding this at the end:

```yaml
# Audio Store @ AURA Engine
sshfs#tankuser@192.168.0.111:/var/audio /opt/aura/audio-store fuse auto,port=22,identityfile=~/.ssh/id_rsa,allow_other,_netdev 0 0

```

Again, check for the correct port number in the line above.

To take this into effect you'll need to remount the filesystem with `sudo mount -a` or reboot the machine. When mounting
you'll need to authenticate with the `tankuser` password once.

Then review if your Tank's Docker configuration mounts the exact same volume (`/opt/aura/audio-store`).
If not edit the tank configuration `/etc/aura/tank.env` and set following property:

```shell
TANK_STORE_PATH=/opt/aura/audio-store
```

Finally, do some testing if the directory is writable from Tank's system (`touch some-file`) and if the Engine's side can read
this file. Then restart your Tank Docker container and you should be good to go.

## Read more

- [Overview](/README.md)
- [Installation for Development](installation-development.md)
- [Installation for Production](installation-production.md)
- [Running with Docker](running-docker.md)
- [Setup the Audio Store](docs/setup-audio-store.md)
- [Developer Guide](developer-guide.md)
- [Engine Features](engine-features.md)
- [Frequently Asked Questions (FAQ)](docs/frequently-asked-questions.md)