Deployment playbook

Choose the right architecture, automate installs, and validate your Velocity rollout.

Last updated October 8, 2025View on GitHub

Deploy Velocity safely

You’ve run the pilot—now it’s time to serve real traffic. This playbook covers architecture choices, automation, and the validation you need before the change window closes.

Pick your topology

Scenario	Recommended pattern	Notes
Single-region pilot or lab	Standalone edge — Velocity terminates UDP/4433 directly	Simplest to operate. Pair with the hardened systemd unit shipped in `docs/systemd/velocity.service`.
Hybrid HTTPS + Velocity rollout	TLS front door + Velocity sidecar	Keep your existing load balancer in front. Ensure it forwards the QUIC connection ID intact or use source-IP pinning.
Global footprint	Regional mesh with anycast or AF_XDP fan-out	Replicate ticket keys via your secret manager and standardise dashboards across PoPs.

Automate the install

Provision runtime hosts with a velocity system account and directories (/etc/velocity, /var/lib/velocity, /var/log/velocity).
Ship binaries via package, cargo build --release --workspace, or container images. Verify checksums from the release page.
Template config into /etc/velocity/serve.<env>.yaml using your favourite IaC tool. Parameterise addresses, cert paths, telemetry targets, and profile policy.
Install service manager hooks. The sample systemd unit enables sandboxing (ProtectSystem=strict, NoNewPrivileges=yes) and UDP watchdog restarts.
Open firewall rules for UDP/4433 and optional TCP fallback. Document the change ticket for audit trails.

Wire certificate automation

velocity-cli cert hybridize \
  --chain /etc/letsencrypt/live/example.com/fullchain.pem \
  --key /etc/letsencrypt/live/example.com/privkey.pem \
  --out /etc/velocity/certs

Schedule renewals with your ACME client and trigger systemctl reload velocity (or velocity-cli admin reload) afterward.
Store hooks in the ACME post-renew directory so they survive upgrades.
Record certificate expiry in your monitoring platform and alert 14 days out.

Validate the rollout

Run this checklist per environment:

velocity --version matches the release you planned.
velocity-cli admin diagnostics --summary shows the expected profiles and ticket rotation cadence.
Prometheus scrapes succeed and dashboards reflect live traffic.
Synthetic requests from at least two regions complete with <45 ms handshake p95.
Downgrade ratio stays under 5% when mixing legacy clients.

Operating patterns

Rolling upgrade: quiesce (velocity-cli admin quiesce), wait for active sessions to drain, deploy the new artefact, resume, then monitor metrics for 15 minutes.
Disaster recovery: replicate /etc/velocity, /var/lib/velocity, and secret material. Rebuild nodes from automation, rotate tickets if compromise is suspected.
Capacity planning: watch velocity_active_connections, CPU utilisation, and packet drops. Scale when CPU p95 exceeds 70% or retransmits climb.

Platform notes

Kubernetes: run as a DaemonSet with hostNetwork: true and a UDP-aware Service (MetalLB, Cilium LB). Mount cert bundles via secrets and rotate with cert-manager webhooks.
Windows edge: deploy the Linux binary via WSL2 or Hyper-V. Use New-NetFirewallRule -Protocol UDP -LocalPort 4433 to permit traffic.
macOS field teams: install via Homebrew, manage with a launchd plist, and disable sleep to keep UDP sockets alive.

Next steps

Keep refining automation by capturing lessons in the Upgrade guide.
Hand this doc to your incident commander and align on the Security overview before GA.