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 URL — http://<host-ip>:4437 — and wait for the green health check.
2. The wizard sees the server is brand new and 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 devices, add the same target and just 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 user pastes it into the wizard’s Invite code field.
• 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.

Upgrades — docker compose pull && docker compose up -d. The app checks the server’s version and shows an update notice on the target row when your container is too old.

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