Deployment Lifecycle
Candidates, health-checked releases, rollbacks and clean-up, for every runtime.
A deployment never replaces a working release with a broken one. The new version is started next to the old one and checked before it takes over.
Stages
fetch shallow git checkout (or docker pull for image apps)build docker build → vpspilot/<app>:<commit>-<deployment>candidate start vp-<app>-candidate on a random loopback porthealth GET <health_path> until < 400, the container exits, or the timeoutrelease stop the live container, start the new one on the host portverify if the new container fails, restore the previous one- Failed before release: the live version is untouched and keeps serving. The deployment is marked failed with the build or health-check output.
- Failed after release: the previous container is renamed back and started, and the deployment is marked failed.
- Succeeded: the deployment becomes the app’s current release. The last five images are kept for rollbacks.
The switch from the old container to the new one takes a few seconds while the host port moves over. Plan deploys of latency-sensitive services accordingly.
systemd apps
fetch shallow git checkoutbuild copy into /srv/vpspilot/<app>/releases/<deployment>, install and build as the app's user in a sandboxed systemd unitcandidate run the release on a spare port ($PORT) as a transient unithealth GET <health_path> until < 400, the process exits, or the timeoutrelease point "current" at the new release, restart vp-<app>.serviceverify if it fails, point "current" back at the previous releaseThe last five releases are kept for rollbacks; a release that never went live is deleted.
Compose apps
fetch shallow git checkout, copied into a release foldercheck docker compose config, then refuse unsafe settingsbuild images tagged per releaserelease docker compose up -d, then GET <health_path> on the public serviceverify if it fails, bring the previous release back upCompose apps have no candidate stage, so changed services restart in place during the release. The previous release is restored if the health check fails.
Failed deployments clean up
An image or release built by a deployment that never went live is removed, together with leftover build layers, so failing pushes don't fill the server's disk.
Triggers
Rollbacks
A rollback re-releases the image of an earlier successful deployment (for systemd and Compose apps, its kept release). It doesn’t rebuild, so it is fast and gives you exactly what ran before. It goes through the same health check as any deploy.
curl -X POST https://pilot.example.com/api/v1/deployments/$DEPLOYMENT_ID/rollback \ -H "Authorization: Bearer $TOKEN"Only successful deployments whose image or release is still on the server can be rolled back to (the last five are kept).