docker-compose.yml

All of vuzon deploys with a single Compose file. This page explains each block of the file, what you can adjust and what is best left as is.

File structure

vuzon runs as a single service: no external database, no queues. The file you downloaded from the repository is this:

services:
  vuzon:
    container_name: vuzon
    image: ghcr.io/kn990x/vuzon
    env_file:
      - path: .env
        required: false
    environment:
      PORT: "8001"
    restart: unless-stopped
    init: true
    read_only: true
    tmpfs:
      - /tmp
    volumes:
      - vuzon-data:/app/data
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    ports:
      - "${VUZON_PORT:-8001}:8001"
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:'+(process.env.PORT||8001)+'/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
      interval: 30s
      timeout: 5s
      start_period: 10s
      retries: 3

volumes:
  vuzon-data:

Image tags

The image is published to ghcr.io/kn990x/vuzon on every release, multi-arch amd64 / arm64. The default tag follows the latest stable release. In production it is worth pinning a concrete version and updating deliberately following the Updating vuzon guide.

Ports and network

vuzon exposes a single HTTP port for the panel and its API. The compose publishes host port VUZON_PORT (default 8001) mapped to the container’s 8001.

Volumes and persistence

There is no database. The only writable path is the vuzon-data volume, mounted at /app/data, which holds:

• Your panel credentials, as a scrypt hash.
• The session signing key the panel generates for itself.

Losing this volume means losing the panel password: the setup wizard reopens and the first visitor claims the panel. Back it up like any other homelab state — see Backups.

Hardening baked in

The compose ships locked down by default, and the image cooperates:

• read_only: true — the image filesystem stays read-only; /tmp lives on tmpfs.
• cap_drop: ALL and no-new-privileges — the container runs as a non-root user with every capability dropped.
• init: true — PID 1 reaps zombies and forwards signals, so docker stop shuts the panel down cleanly.
• A /healthz healthcheck keeps docker ps honest about the panel’s state.

Environment

The two required variables are DOMAIN and CF_API_TOKEN. The full list — ports, data directory, proxy and cookie flags — is in Environment variables.