Skip to content

SEPIA inside virtual environments

Jump to bottom
Florian Quirin edited this page Jul 3, 2022 · 15 revisions

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

May or may not require sudo:

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

Windows

The easiest way (Docker Desktop):

docker volume create sepia-home-share

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 🤷‍♂️ (in Linux it just works).

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: docker run --rm -it --name=sepia_home -p 20726:20726 -v sepia-home-share:/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:

  • docker run --rm -it --name=sepia_home -p 20726:20726 -v sepia-home-share:/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.

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-share'):

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

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

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-share-v2
  • Run your container with BOTH shared folders and terminal access:
docker run --rm -it --name=sepia_home -v sepia-home-share:/home/admin/SEPIA -v /home/[my-user]/sepia-home-share-v2:/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 new Docker volume using the host folder /home/[my-user]/sepia-home-share-v2 (or whatever you've used above)
  • Pull the latest container and start it using your new Docker volume
  • Check if everything is working ^^

Clone this wiki locally