What is pw-launcher?

pw-launcher is a web-based operations console that runs on your server alongside PodWarden. It gives every step of a deployment a name, executes those steps in sequence, and keeps a permanent record of what happened. When something goes wrong, it can restore the previous image and database state automatically.

The problem it solves

Deploying a new version of PodWarden on a self-hosted server is more than swapping an image. A complete deploy involves:

• Taking a database snapshot before anything changes
• Updating the environment file with the new image reference
• Pulling the image from the registry
• Restarting the container
• Waiting for the health-check endpoint to confirm the service is up
• Recording the result

Doing this by hand is error-prone and slow, especially under pressure. If something goes wrong mid-way, recovering to the previous state means reversing each step in the right order — restore the database snapshot, swap the image back, restart. pw-launcher automates the entire forward and reverse sequences so operators do not have to hold the procedure in their head.

Three things pw-launcher does

1. Browse builds from your registry

pw-launcher reads your container registry and shows every available build as a row in the Builds list. Each row displays the build's commit sha (the immutable identifier produced by CI), the tags applied to it — mutable category labels such as :staging and :production, and immutable CalVer version stamps such as v2026.04.24.1 — and the date the image was pushed.

A green LIVE pill marks the build whose image is currently running on the host. The poller checks Docker every 10 seconds, so the badge reflects actual runtime state.

2. Deploy with automatic pre-deploy backup

Select a build in the list, click Deploy, and pw-launcher executes a six-step sequence:

1. pre-deploy-backup — takes a full PostgreSQL snapshot of the PodWarden database before any change is made
2. write-env — updates the environment file on disk to reference the new image tag
3. pull-image — pulls the new image from the registry
4. swap-container — restarts the target container with the new image
5. health-check — polls the stack's configured health-check URL until it returns a healthy response, or times out
6. finalize — records the deploy as successful in the history

Deploy progress streams live to your browser. If any step fails, the sequence stops and the pre-deploy state is preserved. The database snapshot taken in step 1 remains available for a rollback.

3. Roll back in two clicks

If a deploy produces a problem, pw-launcher offers two rollback paths directly from the Builds list:

• Full rollback — swaps the image back to the previous build and restores the database from the snapshot taken before the failed deploy. This is the primary recovery path when a deploy has migrated or corrupted the database.
• Image-only rollback — swaps the image back without touching the database. Use this when the schema was not changed, when the snapshot has been pruned, or when you want to avoid restore downtime.

Both paths execute as the same six-step FSM in reverse, with real-time progress in the browser.

Who it is for

pw-launcher is built for operators who self-host PodWarden:

• Anyone doing regular deploys who wants an auditable history of every operation
• Teams that need the safety of pre-deploy database backups without maintaining a separate backup workflow
• Operators who want a clear view of which build is running, which one is tagged :production, and whether the two have drifted apart

Local-only by design

pw-launcher runs on your server at port 8080 and is never exposed to the public internet. Operators reach it over LAN or through their own VPN — the same network path they use to SSH into the server.

This is a deliberate design decision, not a limitation. pw-launcher can restart containers and restore database state, so access is protected at the network level. There is no separate public-facing auth layer to maintain, no TLS certificate to rotate for an internal tool, and no risk of accidentally exposing deployment controls to the internet.