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

Create a private backup directory once:

sudo install -d -o vsync -g vsync -m 700 /var/backups/vsync

Then snapshot metadata and manifests while the service is running:

vsync_backup_stamp="$(date +%F-%H%M)"
sudo -u vsync vsync-server backup \
  /var/backups/vsync/meta-$vsync_backup_stamp.sqlite
sudo tar -C /var/lib/vsync -czf \
  /var/backups/vsync/manifests-$vsync_backup_stamp.tgz manifests

The backup command writes a consistent snapshot even while the server is handling traffic, and refuses to overwrite an existing file - date-stamp the name. Manifest files never change once written, so archiving manifests/ live is also safe. Do not copy meta.sqlite itself: it uses SQLite WAL mode, and a raw copy of a live database is torn.

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

Restore a backup

Test this procedure on a separate server before relying on a backup. For an in-place recovery, stop Vsync and preserve the failed data directory:

sudo systemctl stop vsync-server
sudo mv /var/lib/vsync /var/lib/vsync.before-restore
sudo install -d -o vsync -g vsync -m 750 /var/lib/vsync
sudo install -o vsync -g vsync -m 600 \
  /var/backups/vsync/meta-2026-07-19-1200.sqlite \
  /var/lib/vsync/meta.sqlite
sudo tar -C /var/lib/vsync -xzf \
  /var/backups/vsync/manifests-2026-07-19-1200.tgz
sudo chown -R vsync:vsync /var/lib/vsync
sudo systemctl start vsync-server
curl https://builds.example.com/healthz

Replace the example timestamps with one matching backup set. Restore objects/ before starting when it was backed up. Without it, the catalog is restored but builds cannot be fetched until their chunks are recovered from another backup, an original build, or client caches.

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 the configured number of newest builds of each stream and platform, 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.

Integrity scrub

Re-hash every stored chunk and manifest and report which builds a bad object leaves broken:

sudo -u vsync vsync-server fsck

This finds bit rot proactively instead of letting it surface as a failed fetch. A corrupt object is removed, so the server asks for it again during have-negotiation and the next commit that contains the same content re-uploads it - damaged builds repair themselves without a restore, as soon as such a commit happens. --dry-run reports without removing anything.

fsck exits nonzero when it finds any damage and records what it removed in the activity trail, so a scheduled run (say weekly, via cron or a systemd timer) doubles as a bit-rot alarm. It reads every chunk once; expect a disk-bound runtime on large stores. It is safe while the server is running.

Upgrade

Take a metadata backup before every upgrade. Download the new package and install it over the existing version:

sudo apt install ./vsync-server_*-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. Database migrations run when the new server starts. An older server refuses a newer schema, so downgrading across a migration requires the pre-upgrade metadata backup.

When a release changes the wire protocol, old and new clients refuse each other and name the side that needs updating. Coordinate that server and client rollout. Transfers interrupted by the restart can be run again; commits are atomic on the server.

Logs

sudo journalctl -u vsync-server -f

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