Storage, backups, and upgrades

Data layout

With the packaged defaults, server data lives in /var/lib/vsync:

meta.sqlite   users, builds, streams, flags, and activity
manifests/    immutable build manifests
objects/      content-addressed chunks

Metadata and manifests are small and essential. Chunks are much larger, but may be recoverable from original builds or client caches.

Back up safely

The metadata database uses SQLite WAL mode. Do not copy only meta.sqlite while the service is running.

For a simple consistent backup, briefly stop the service:

sudo systemctl stop vsync-server
sudo tar -C /var/lib/vsync -czf /backup/vsync-metadata.tgz meta.sqlite manifests
sudo systemctl start vsync-server

Back up objects/ as well when storage and backup bandwidth allow. Keep at least one backup outside the VPS.

Test restoration periodically on a separate directory or server.

Garbage collection

Preview a sweep:

sudo -u vsync vsync-server gc --dry-run

Run it immediately:

sudo -u vsync vsync-server gc

Garbage collection retains current stream tips, configured stream history, pinned builds, and young builds. A grace period prevents newly written files from being collected during an in-flight operation.

The server normally sweeps at startup and once per day. You can also preview or run a sweep from the admin dashboard.

Upgrade

Download the new package and install it over the existing version:

sudo apt install ./vsync-server_<new-version>-1_amd64.deb
sudo systemctl restart vsync-server
curl https://builds.example.com/healthz

The package preserves /etc/vsync/server.toml and /var/lib/vsync. Take a metadata backup before upgrades that include database migrations.

Logs

sudo journalctl -u vsync-server -f

The admin activity trail records user-facing events such as logins, pushes, fetches, stream moves, flags, token changes, and garbage collection. systemd logs remain the source for startup errors and operational failures.