Home Sync with Docker

This is the recommended way to run Home Sync: a single container on any host with Docker — a Synology or TrueNAS box, Unraid, a Raspberry Pi, or an always-on machine.

Prerequisites

• Docker 20.10+ with Compose v2.
• A directory you’re happy persisting data to (for example /mnt/nas/vetroscope).
• A licensed Vetroscope on the devices that will sync (trials work too).

1. Deploy the container

curl -LO https://raw.githubusercontent.com/rankin-works/vetroscope-home-sync/main/docker-compose.yml
docker compose up -d

The stock file uses a named volume and port 4437. To keep the data somewhere specific (recommended on a NAS), point the volume at a real path before starting:

services:
  vetroscope-home-sync:
    image: ghcr.io/rankin-works/vetroscope-home-sync:latest
    container_name: vetroscope-home-sync
    restart: unless-stopped
    ports:
      - "4437:4437"
    environment:
      VS_SERVER_NAME: "Jake's Home Sync"   # the name shown in the app
    volumes:
      - /mnt/nas/vetroscope:/data

Check it’s alive:

curl http://<host-ip>:4437/health
# → {"ok":true,"version":"…","users":0,...}

2. Grab the setup code

First boot prints a one-time setup code to the logs:

docker compose logs vetroscope-home-sync | grep "Setup code"
# [home-sync]   Setup code: V7K2-9ABM-X4FT

It won’t appear again — once setup completes, the code is dead.

3. Connect Vetroscope

On your desktop: Settings → Sync → Add sync target → Home Sync.

1. Enter the server address — http://<host-ip>:4437 — and wait for the green check mark.
2. Because the server is brand new, Vetroscope asks for the setup code; enter it with the email, password, and display name for the admin account (yours).
3. Complete the encryption step — reuse your existing encryption key or generate one, and store it in a password manager.
4. The first sync pushes your history to the server.

On your other computers, add the same Home Sync server and sign in with the account you created.

Adding other people

Each user gets their own account (and needs their own Vetroscope license). Registration mode is controlled by VS_ALLOW_REGISTRATION:

• invite (default) — an admin generates a one-time invite code; the new person pastes it into the Invite code box during setup.
• open — anyone who can reach the server can register.
• closed — no new accounts at all.

Configuration reference

Variable	Default	What it does
VS_SERVER_NAME	hostname	Friendly name shown in the app
VS_PORT	4437	Listen port
VS_DATA_DIR	/data	Where the database and backups live
VS_ALLOW_REGISTRATION	invite	open / invite / closed
VS_MAX_DEVICES_PER_USER	10	Per-user device cap
VS_TLS_CERT / VS_TLS_KEY	unset	PEM cert + key for built-in HTTPS
VS_LOG_LEVEL	info	debug / info / warn / error
VS_ENABLE_METRICS	false	Adds a Prometheus /metrics endpoint

Maintenance

Admin commands run inside the container via vhs-cli:

docker exec vetroscope-home-sync vhs-cli list-users
docker exec vetroscope-home-sync vhs-cli reset-password --email jake@example.com --password <new>
docker exec vetroscope-home-sync vhs-cli revoke-tokens --email jake@example.com
docker exec vetroscope-home-sync vhs-cli rotate-jwt-secret --confirm

(create-user, promote, and demote exist too — vhs-cli help lists everything.)

Backups — everything lives in the data directory. For a consistent snapshot while the server runs:

docker exec vetroscope-home-sync sqlite3 /data/sync.db ".backup '/data/sync.db.bak'"

then copy the data directory into your normal NAS backup routine.

Updates — docker compose pull && docker compose up -d. Vetroscope checks your server’s version and shows Update Home Sync or Update available next to it in Settings → Sync when there’s a newer one.

Next: Remote access and HTTPS for syncing away from home, and the full setup guide on GitHub.