Operating Astro SSR in Production with Podman

A short runbook for the Astro container on the VPS: start and stop, health checks, the four-command update, rollback by commit and Caddy checks.

Shipping the site was the satisfying part. What matters in the long run is knowing, three months later, how to check the logs, push an update or roll back. I wanted a runbook short enough to keep in my head, not a wiki I would never open. This is what I settled on for my old Astro site.

The setup

  • Host: Debian VPS, Podman with podman-compose (deployed like this).
  • Working directory: /opt/website. The Git checkout is also the deploy root.
  • Proxy: Caddy on 80 and 443, the container on 127.0.0.1:4321.

Start and stop

From the project directory:

cd /opt/website
podman-compose -f compose.yml up -d
podman-compose -f compose.yml down

For a single container, for example after a crash loop, the plain podman verbs are fastest:

podman stop website
podman start website
podman restart website

Health checks

podman ps
podman logs -f website
curl -I http://127.0.0.1:4321
curl -I https://adrian-altner.de

An HTTP status code is the clearest signal I have: faster than reading logs, less ambiguous than ps.

Deploy an update

The update has to be short enough to get right at 11 pm. Four commands, always the same:

cd /opt/website
git pull
podman-compose -f compose.yml up --build -d
podman image prune -f

git pull brings in the change and up --build -d rebuilds and replaces the running container. image prune -f keeps the disk from filling up with orphaned build layers. Updating the Website Repository on a VPS goes through this flow in more detail.

Roll back

When the newest build is worse than the one before, check out the previous commit and rebuild. No image registry is needed, because the image can be rebuilt from source:

cd /opt/website
git log --oneline -n 5
git checkout <previous-commit>
podman-compose -f compose.yml up --build -d

If a version turns out to be a regression worth remembering, I tag it afterwards. The next rollback then needs no digging for commit hashes.

When Caddy looks wrong

Most HTTPS incidents on this server were DNS drift, a port that had changed or a proxy target that had moved. Caddy itself almost never broke. Three commands cover it:

sudo systemctl status caddy --no-pager
sudo journalctl -u caddy -n 100 --no-pager
sudo caddy validate --config /etc/caddy/Caddyfile

Takeaways

  • A single-service setup needs three properties: observable (logs, status, curl, in that order), repeatable (up --build -d does the same every time) and reversible (a commit hash and a rebuild).
  • A deploy you can run half asleep is worth more than a clever pipeline.
  • Keep the command surface small. The fewer verbs you need, the fewer you forget.

More on this

Topic
  • Self-Hosting Running services on a server you control instead of using a provider's hosted version, with the upkeep that comes with it.
Builds on
Uses
  • Caddy Web server and reverse proxy that obtains and renews TLS certificates on its own, configured in a short Caddyfile.
  • Podman Container engine without a background daemon that runs rootless by default on Linux and uses the same commands on macOS and on a server.
Mentioned in
  • Astro SSR with Podman: From Local Setup to VPS Astro with the Node standalone adapter in a two-stage Podman container, run locally with the same compose file that later goes to the VPS.
  • My Old Astro Website My old site at adrian-altner.de: Astro with the Node adapter, typed content collections, IndieWeb features and photos as files with JSON sidecars.
Mentioned

Show in the graph view →