Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Install and configure

Install the Linux package

Download the current .deb from the Vsync downloads page and install it:

sudo apt install ./vsync-server_<version>-1_amd64.deb

The package installs:

  • /usr/bin/vsync-server
  • /etc/vsync/server.toml
  • vsync-server.service
  • A locked-down vsync system user
  • /var/lib/vsync for server data

The service is not automatically enabled on first installation. Review the configuration before starting it.

Configure the server

Edit /etc/vsync/server.toml:

root = "/var/lib/vsync"
addr = "127.0.0.1:7770"

# Optional integrations:
# p4 = "ssl:perforce.example.com:1666"
# webhook = "https://hooks.example.com/services/..."

[gc]
enabled = true
keep_history = 14
keep_days = 7

Settings mean:

  • root: chunks, manifests, and metadata location.
  • addr: local address and port on which the HTTP server listens.
  • p4: exact P4PORT used to validate Perforce tickets.
  • webhook: optional Slack- or Discord-compatible incoming webhook.
  • gc.enabled: run garbage collection at startup and daily.
  • gc.keep_history: retain this many previous builds per stream.
  • gc.keep_days: retain builds younger than this many days.

Unknown settings are rejected so configuration mistakes do not silently pass. Command-line arguments override file values. Use --config <path> or VSYNC_SERVER_CONFIG=<path> to select a different file.

Start the service

sudo systemctl enable --now vsync-server
sudo systemctl status vsync-server
curl http://127.0.0.1:7770/healthz

The health endpoint should return ok.

After changing server.toml:

sudo systemctl restart vsync-server

Create the first administrator

Start the service once so it creates its database with the correct ownership, then create an admin token as the service user:

sudo -u vsync vsync-server token create admin --admin

The token is displayed once. Store it securely and use it to sign in at https://<your-server>/admin after HTTPS is configured.

Experimental Windows server

Extract the Windows server zip, create a writable data directory and a server.toml, then run:

vsync-server.exe --config C:\Vsync\server.toml serve

Run it behind an HTTPS reverse proxy. The current package does not install a Windows Service; use Linux for unattended production deployment.