Composition and environment files¶

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

Compose files

Compose files live under compose/ in the repository. Run commands from that directory or pass --env-file compose/.env and --file compose/<name>.

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. The names below reflect the bundle layout shipped in compose/.

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.skills-extra.yml`		Install additional optional skills
`docker-compose.hivemind.yml`		Install HiveMind components
`docker-compose.server.yml`		Lightweight server stack (core + messagebus + HiveMind)
`docker-compose.macos.yml`		Install core components (except the GUI)
`docker-compose.windows.yml`		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

Server-only stack¶

The docker-compose.server.yml bundle runs a lightweight stack with ovos_messagebus, ovos_core, and HiveMind services. It omits audio, listener, and GUI containers, making it a good fit for headless deployments or a central HiveMind hub.

Raspberry PiLinuxMac OSWindows WSL2

docker compose --project-name ovos --file docker-compose.server.yml up --detach

docker compose --project-name ovos --file docker-compose.server.yml up --detach

docker compose --project-name ovos --file docker-compose.server.yml --env-file .env up --detach

docker compose --project-name ovos --file docker-compose.server.yml --env-file .env up --detach

To expand beyond the server stack, switch to docker-compose.yml and add other bundles like docker-compose.skills.yml or docker-compose.gui.yml.

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`		Raspberry Pi tuned defaults and GPIO/I2C/SPI group IDs

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

Variable	Default	Description
`DISPLAY`	`:0`	Display used by X or Wayland
`PULSE_SERVER`	Platform-specific	PulseAudio server address
`GPIO_GID`	`997`	`gpio` group ID on Raspberry Pi
`HIVEMIND_CONFIG_FOLDER`	`/home/hivemind/hivemind/config`	HiveMind configuration directory
`HIVEMIND_CONFIG_PHAL_FOLDER`	`/home/hivemind/hivemind/config/phal`	HiveMind PHAL configuration directory
`HIVEMIND_SHARE_FOLDER`	`/home/hivemind/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`	`/home/ovos/ovos/config`	OVOS configuration directory
`OVOS_CONFIG_PHAL_FOLDER`	`/home/ovos/ovos/config/phal`	OVOS PHAL configuration directory
`OVOS_PERSONA_FOLDER`	`/home/ovos/ovos/config/persona`	OVOS persona directory
`OVOS_SHARE_FOLDER`	`/home/ovos/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 EGLFS KMS configuration
`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`	`/home/ovos/ovos/tmp`	OVOS temporary directory
`TZ`	`UTC`	Timezone to set in the container
`VERSION`	`alpha`	Container image tag to pull
`VIDEO_GID`	`44`	`video` group ID
`WAYLAND_DISPLAY`	`wayland-0`	Compositor used by Wayland
`XDG_RUNTIME_DIR`	`/run/user/1000`	Path to XDG runtime directory

Do not change OVOS_USER or HIVEMIND_USER

The OVOS_USER and HIVEMIND_USER variables should not be changed unless you build your own container images with a different user.

How to get the GID?¶

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

Raspberry PiLinux

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 variable requires a UID. This UID is the unique ID of the current user who will run the docker compose or podman-compose command.

LinuxWindows WSL2

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.