GLOSSA LISTEN DOCUMENTATION · SERVER
Run Glossa Listen with Docker Compose
Applies to Glossa Listen v1.0.0
Use Docker Compose to run Glossa Listen and keep its database, audiobook files, import inbox, and backups in folders on the host.
This guide uses fouronefourlabs/glossa.listen:latest as a provisional image name. The published image name and tag will be confirmed before release; this Compose example is not ready to deploy until that image is available.
Before you begin
- A Linux host or development computer with Docker Engine and the Docker Compose plugin.
- Enough disk space for the database, audiobook files, imports, and backups. The audio library can grow independently of the container image.
The container listens on port 8080. The example publishes it on host port 6776 and checks service health at /api/health.
Create the folders
Make a directory for the Compose project, then create the persistent folders beside the Compose file:
mkdir -p glossa-listen/{data,audiobooks,import,backup}
cd glossa-listenThe container runs as UID/GID 10001. Give it write access to the data, audiobook, and backup folders, and read/traverse access to the import folder:
sudo chown -R 10001:10001 data audiobooks backup
sudo chown -R 10001:10001 importCompose file
Save this as compose.yaml in the project directory:
services:
glossa:
image: fouronefourlabs/glossa.listen:latest
container_name: glossa-listen
restart: unless-stopped
ports:
- "${GLOSSA_PORT:-6776}:8080"
volumes:
- ./data:/data
- ./audiobooks:/audiobooks
- ./import:/data/import:ro
- ./backup:/data/backups
healthcheck:
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/api/health', timeout=4)"]
interval: 30s
timeout: 5s
retries: 3Storage paths: data holds the database and settings; audiobooks holds media and artwork; import is the automatic import inbox; and backup holds local snapshots.
Host port 6776 maps to container port 8080. Set GLOSSA_PORT to change the host port. Keep the database and media folders persistent when replacing or updating the container.
Start and check the service
Start the container after the image is published or available in your registry:
docker compose up -d
docker compose ps
docker compose logs -f glossaOpen http://localhost:6776 on the host. From another device on your LAN, use the host's LAN address, for example http://192.168.1.20:6776. The first account created on a new server becomes its administrator. Before allowing access from the internet, put the service behind HTTPS using the reverse proxy guide.
To use a different host port, start Compose with GLOSSA_PORT=7000 docker compose up -d; then open http://localhost:7000.
Use the automatic import inbox
The server scans /data/import every 30 seconds and waits until files remain unchanged for at least 60 seconds. Add a complete audiobook file or one folder per book. Embedded book details are used when available; otherwise a unique exact AudioSilo match may be selected. Ambiguous or incomplete matches appear in Administration → Auto import → Needs review. The inbox source files stay in place, and successfully imported files are copied into the library. See the server guide for the review workflow.
Stop, update, and back up
Stop the container while keeping its data folders:
docker compose downWhen a new image is available, pull it and recreate the container:
docker compose pull
docker compose up -dKeep data, audiobooks, import, and backup when updating or moving the host. Back up the database and audiobook files separately from the host if you need protection from disk failure. Glossa Listen also supports local snapshots and optional S3-compatible backups from its administration page. Check the service with docker compose ps and docker compose logs glossa.

