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.

Draft image name

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-listen

The 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 import

Compose 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: 3

Storage 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 glossa

Open 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 down

When a new image is available, pull it and recreate the container:

docker compose pull
docker compose up -d

Keep 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.

After the server is runningConfigure your library