Docker Volume Configuration#

Zerobyte stores all persistent state — SQLite database, restic password file, restic cache, volume mount points, and repository data — under a single root path inside the container: /var/lib/zerobyte. Mapping a host directory to this path is the only volume mount required in production.

The /var/lib/zerobyte Root#

constants.ts defines the default paths for every persistent resource:

Because every default path is under /var/lib/zerobyte, a single bind-mount covers everything 1.

Production Setup#

The canonical README install snippet uses a single host bind-mount:

volumes:
  - /etc/localtime:/etc/localtime:ro
  - /var/lib/zerobyte:/var/lib/zerobyte

The /etc/localtime mount is read-only and is used for accurate backup scheduling when TZ is not set 2.

Warning: Do not point /var/lib/zerobyte at a network share. The README explicitly warns this causes permission issues and strong performance degradation — particularly relevant for SQLite, which requires low-latency fsync.

TrueNAS: /var/lib is ephemeral on TrueNAS and is wiped on system upgrades. Use a dedicated ZFS dataset instead 3:

volumes:
  - /etc/localtime:/etc/localtime:ro
  - /mnt/tank/docker/zerobyte:/var/lib/zerobyte

Development Setup#

The development service in compose.yaml also mounts /var/lib/zerobyte directly from the host, plus additional mounts for live code reloading and test data:

volumes:
  - /etc/localtime:/etc/localtime:ro
  - /var/lib/zerobyte:/var/lib/zerobyte # persists database + all state
  - ./app:/app/app # live-reload source
  - ~/.config/rclone:/root/.config/rclone:ro
  - ./tmp/:/test-data

zerobyte-prod (Local Test Target in compose.yaml)#

The zerobyte-prod service in compose.yaml redirects the data root to a local ./data directory rather than the system-wide /var/lib/zerobyte:

volumes:
  - /etc/localtime:/etc/localtime:ro
  - ~/.config/rclone:/root/.config/rclone:ro
  - ./tmp:/test-data
  - ./data:/var/lib/zerobyte # local project dir for testing

This keeps test state isolated from the system-level data directory.

E2E Test Setup#

The zerobyte-e2e service 4 mounts only the data subdirectory rather than the full root, pointing it at a Playwright-specific path:

- ./playwright/data:/var/lib/zerobyte/data

This scopes persistence to just the database and password file (/var/lib/zerobyte/data/), leaving volumes and repositories ephemeral for test isolation.

Overriding Individual Paths#

All five paths can be overridden individually via environment variables 1. This is used in non-Docker local dev, where the README recommends a .env.local file pointing all paths to a local ./data/ subdirectory:

ZEROBYTE_DATABASE_URL=./data/zerobyte.db
RESTIC_PASS_FILE=./data/restic.pass
RESTIC_CACHE_DIR=./data/restic/cache
ZEROBYTE_REPOSITORIES_DIR=./data/repositories
ZEROBYTE_VOLUMES_DIR=./data/volumes

Key References#

• constants.ts — canonical default paths for all persistent resources
• compose.yaml — dev, prod, and e2e volume configurations
• README.md installation section — production setup guide including TrueNAS and network-share warnings