Skip to content

Composition and environment files

The easiest and quickest way to deploy Open Voice OS containers is to use a composer such as docker composer or podman-compose.

Composition files

Composition files provide an easy way to provision the stack (services and volumes) with the required options and configuration for each of the services.

Compose file Platforms Description
docker-compose.yml Install core components (except the GUI)
docker-compose.gui.yml Install GUI components
docker-compose.skills.yml Install pre-defined skills
docker-compose.hivemind.yml Install HiveMind components
docker-compose.macos.yml Install core components (except the GUI) Install core components (except the GUI)
docker-compose.raspberrypi.yml Add GPIO support to ovos_core component
docker-compose.raspberrypi.gui.yml Add /dev/vchiq to ovos_gui component

Environment files

A Docker or Podman environment file contains lines about environment variables that are usable by the Docker or Podman command line. It is a convenient way to pass many environment variables to a single command.

Environment file Platforms Description
.env Set of variables used by the composition files
.env-raspberrypi Add GPIO_GID, I2C_GID and SPI_GID variables

Some variables might need to be tuned to match your setup such as the TZ, XDG_RUNTIME_DIR, etc...

Variable Default Platforms Description
DISPLAY :0 Display used by X or Wayland
GPIO_GID 997 gpio group ID on Raspberry Pi
HIVEMIND_CONFIG_FOLDER ~/hivemind/config HiveMind configuration directory
HIVEMIND_CONFIG_PHAL_FOLDER ~/hivemind/config/phal HiveMind PHAL configuration directory
HIVEMIND_SHARE_FOLDER ~/hivemind/share HiveMind shared directory
HIVEMIND_USER hivemind User running in the container
I2C_GID 994 i2c group ID on Raspberry Pi
INPUT_GID 102 input group ID
OVOS_CONFIG_FOLDER ~/ovos/config OVOS configureation directory
OVOS_CONFIG_PHAL_FOLDER ~/ovos/config/phal OVOS PHAL configureation directory
OVOS_SHARE_FOLDER ~/ovos/share OVOS shared directory
OVOS_USER ovos User running in the container
PULL_POLICY always Policy to pull Docker images
QT_QPA_EGLFS_INTEGRATION eglfs QT preferred backend to use for EGLFS
QT_QPA_EGLFS_KMS_CONFIG /home/$OVOS_USER/.config/mycroft/ovos-eglfs.json QT KSM backend configuration for WGLFS
QT_QPA_PLATFORM eglfs QT platform plugin to use
RENDER_GID 106 render group ID
SPI_GID 995 spi group ID on Raspberry Pi
TMP_FOLDER ~/ovos/tmp OVOS temporary directory
TZ America/Montreal Timezone to set in the container
VERSION alpha Container image tag to pull
VIDEO_GID 44 video group ID
XDG_RUNTIME_DIR /run/user/1000 Path to XDG runtime directory


The OVOS_USER and HIVEMIND_USER variables should not be changed except if you build your own container images which a different one.

How to get the GID?

The getent command could be used in order to get the GID of gpio and render groups.

getent group gpio
getent group render
getent group video
getent group input
getent group i2c
getent group spi
getent group render
getent group video
getent group input

How to get the UID?

The XDG_RUNTIME_DIR variables requires a UID, this UID is the unique ID of the current user which will run the docker compose or podman-compose command.

echo $UID
echo $UID

XDG Base Directory

Mac OS doesn't leverage XDG_RUNTIME_DIR variable as there is no support of XDG Base Directory on Mac OS.