Deploy & build

Sources

• GitHub, GitLab, Bitbucket, Gitea (OAuth / app providers)
• Generic Git (HTTPS or SSH key)
• Docker image (public or private registry)
• Zip upload
• Compose: paste raw YAML, clone from Git, or create from a raw compose URL

Builders

• Nixpacks and Railpack
• Dockerfile
• Heroku / Paketo buildpacks (amd64-only images — prefer nixpacks, railpack or Dockerfile on arm64)
• Static → nginx
• BuildKit cache for faster rebuilds

The queue

• Durable: the deployment table is the queue, so a restart, a crash or a SIGKILL mid-build never loses the backlog — queued rows are simply claimed on the next boot
• Statuses are queued → running → done | error | cancelled, streamed live over a WebSocket
• FIFO per target server, with a per-app mutex: two jobs for one service never build at once
• A burst of pushes coalesces — the older queued row is superseded (and reported as cancelled, not as a failure), so at most one running plus one queued job per app
• Cancel from the UI or the CLI; boot recovery fails deployments a restart interrupted
• Deploy concurrency is per server (NIXPLOY_DEPLOY_CONCURRENCY, default 1)

Lifecycle

• Deploy / redeploy / start / stop / reload
• Swarm rolling updates — a failed deploy leaves the previous revision up
• A convergence gate waits for one task to actually reach running (after the image's HEALTHCHECK) before the deploy is called successful; three failed tasks fail it with the engine's reason
• One-click rollback to a previous successful image — the newest 5 pins per app are kept
• Compose rollback restores the stack's compose file and its service-level env from a snapshot taken at each render
• Optional push of the built image to a registry, so replicas on other nodes and rollbacks after a node swap can pull it
• Docker-image sources can auto-update: hourly digest check, redeploy when the tag moves

Deploy hooks

A pre-deploy command (migrations, say) runs in a throwaway container built from the image this job just produced, with the merged runtime env handed over a 0600 env file — never on argv. A non-zero exit aborts the deploy before the rollout, so the old version keeps serving. The post-deploy command runs once the rollout converges.

• The image must contain a shell: the hook overrides the image's own ENTRYPOINT with sh, and exit 127 means there is no /bin/sh (scratch and distroless images cannot host one)
• Hooks are time-boxed by NIXPLOY_HOOK_TIMEOUT_MS (default 10 minutes); the container and the env file are always cleaned up
• Previews never run them — a pull request's migration must not touch the environment production shares

Provenance

Every deployment records what started it (manual, api, webhook, schedule, preview, rollback, redeploy, gitops, system) and who. Push webhooks fill in the commit SHA, message and author; after a checkout the worker reads them from git when the payload did not carry them, and a docker-image source stores the registry digest. The history table renders the trigger, the short SHA linked to the provider's commit page, and the author.

Advanced (applications)

• Mounts (volume / file content), published ports, redirects, basic auth
• Healthchecks, placement constraints, replicas & resources
• Swarm tuning: rolling update, rollback, restart policy, global mode, service labels, extra networks
• Watch paths — only deploy a push when a matching file changed
• Duplicate a service or move it to another environment