SEPIA inside a Docker Container

When running SEPIA-Home inside a Docker container there are a few things you need to take care of to make the system stable and to make data persistent.

Get your container

You can pull pre-built containers from Docker Hub: https://hub.docker.com/repository/docker/sepia/home

Set up your host system properly

The Docker container will inherit certain properties of your host system (the machine running Docker). One of these properties is about virtual memory (mmap counts) and is important for the Elasticsearch database used by SEPIA.
Usually you would set sudo sysctl -w vm.max_map_count=262144 in your Linux system before running Elasticsearch, but this will not work inside Docker. You need to run the command BEFORE starting your container.

On some systems like Windows and Mac you probably need to enter the virtual machine first that runs the Docker engine. Try one of these commands:

• Windows / Docker Toolbox: docker-machine ssh
• Windows / Docker Desktop (MobyLinuxVM): check sysctl vm.max_map_count inside your container, it might already be OK. If not use the docker run --privileged flag to start your container or check the docker deamon config file (untested).
• Mac (xhyve virtual machine): screen ~/Library/Containers/com.docker.docker/Data/vms/0/tty

Inside this machine enter sudo sysctl -w vm.max_map_count=262144.

Create a shared volume

Your SEPIA-Home installation needs to have a place to store data persistently. The most comfortable solution is to create an EMPTY Docker volume in advance and add this to your run script. This way the Docker container will automatically copy over all necessary data to the empty volume on start. Here is how this works.

Linux

SEPIA_SHARE=/home/[my-user]/sepia-home-data && mkdir -p $SEPIA_SHARE
sudo docker volume create --opt type=none --opt device=$SEPIA_SHARE --opt o=bind sepia-home-data

Windows

The easiest way (Docker Desktop):

docker volume create sepia-home-data

The drawback: This will create a volume inside your Docker VM (e.g. MobyLinuxVM) which is hard to manage if you want to create a backup of your SEPIA data. It will be shared with other containers though.

It is surprisingly complicated to handle this properly in Windows :-/. If you simply add a folder to the run command, for example via Docker Desktop the container will most likely fail to copy over the data and your folder stays empty :man_shrugging:. According to the official Docker docs the "bind mount" (folder added via run) should work if it didn't exist before.

Alternative (any system)

Use docker cp to copy the SEPIA user data folder (since v2.6.2: /home/admin/sepia-home-data) from your container to your host system and then use the '-v' option with the path to your folder instead of the volume name.
In Windows you might need to do some additional configuration via the 'shared drives' page of the Docker settings.

Run SEPIA-Home setup on first start

Before you can run the server you need to set up the database and core-accounts. In newer containers (v2.6.2+) this is done automatically at first start and the user data will be stored in a single shared folder (internal folder '$HOME/sepia-home-data'), e.g.:

• Start the container: sudo docker run --rm -it --name=sepia_home -p 20726:20726 -v sepia-home-data:/home/admin/sepia-home-data sepia/home:latest
• After the first start and a successful setup check the folder $SEPIA_SHARE/setup/automatic-setup for the file results.log. There you will find the randomly generated passwords for admin, assistant and first user. Delete the file after you have memorized the passwords ;-)

If you want to make individual changes or run the setup manually you can start the container with terminal access:

• sudo docker run --rm -it --name=sepia_home -p 20726:20726 -v sepia-home-data:/home/admin/sepia-home-data sepia/home:latest /bin/bash
• NOTE: If you make changes that are not stored inside the shared folder (like TTS or NGINX settings) you might need to create additional volumes to make this changes persistent (see below).

If you want to run the automatic-setup once again with a modified config.yaml you need to create an (empty) file called docker-setup inside your shared folder $SEPIA_SHARE/setup/automatic-setup next to the config. NOTE: If you start the container again this will completely RESET your database!

Default run command

The default run command for your SEPIA container should make a port available to access the SEPIA server (recommended 20726 but can be anything) and mount your volume (earlier we called it 'sepia-home-data'):

sudo docker run --rm --name=sepia_home -p 20726:20726 -v sepia-home-data:/home/admin/sepia-home-data sepia/home:latest

(may or may not require sudo, depending on your setup)

Custom Nginx setup for SSL (another shared volume)

If you're planning to manage SSL (HTTPS) inside your container, e.g. with the self-signed option, you need to add the Nginx config folder to your persistent data. The procedure is basically identical to the setup of the previous shared folder:

• Create an EMPTY shared folder: SEPIA_SHARE_NGINX=/home/[my-user]/sepia-home-nginx && mkdir -p $SEPIA_SHARE_NGINX
• Make a Docker volume out of it: sudo docker volume create --opt type=none --opt device=$SEPIA_SHARE_NGINX --opt o=bind sepia-home-nginx
• Add this flag to your run command: -v sepia-home-nginx:/etc/nginx/sites-enabled

NOTE: If you do this after the first run of SEPIA-Home and you want to use SSL by default you have to manually run the SSL setup inside the container again (see "terminal access" in "first start" section above).

Custom TTS engines

There are a hand full of additional TTS systems you can set up for SEPIA. They are not enabled by default because of the license (e.g. MBROLA) or resource requirements (Mary-TTS). If you install them manually the container will forget the changes after it is closed because the TTS systems are not yet included in the persistent data folder. You can add another shared volume for /home/admin/SEPIA/sepia-assist-server/Xtensions/TTS but this will have the drawback of not getting updates anymore via next Docker pull.
You can however run any Mary-TTS API compatible server (Mary-TTS, Larynx, Mimic3, etc.) outside of your SEPIA container and add it to your setup via the marytts_server field in your SEPIA settings (see SEPIA Control-HUB -> core settings page).

Update your container

Backup your SEPIA shared folder (Docker volume) on your host machine before you start! ;-)

For newer containers (v2.6.2+) you can simply pull the latest container to update your server.

If you have an older container (v2.6.1 or older) please follow these steps:

• Close your existing container
• Create an EMPTY folder for the new user data folder, e.g.: mkdir /home/[my-user]/sepia-home-data
• Run your container with BOTH shared folders (assuming the old one is sepia-home-share) and terminal access:

sudo docker run --rm -it --name=sepia_home -v sepia-home-share:/home/admin/SEPIA -v /home/[my-user]/sepia-home-data:/home/admin/sepia-home-data sepia/home:[your-version] /bin/bash

• Inside your container go to $HOME/SEPIA and run the update script manually: bash update-sepia.sh
• If the process was successful enter the folder again cd $HOME/SEPIA and run bash scripts/create-external-data-folder.sh. This will create and set up the new user folder, moving all your stuff from your current Docker volume.
• Exit the container: exit
• Create a Docker volume named sepia-home-data using the new host folder /home/[my-user]/sepia-home-data (or whatever you've used above)
• Pull the latest container and start it using your new Docker volume. Remove the old volume!
• Check if everything is working ^^