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.
Reviewed by adrian
on
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
80and443, the container on127.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 -ddoes 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.
Based on
-
Operating Astro SSR in Production with Podman
(
raw/2026/2026-03-04/operating-astro-ssr-in-production-with-podman.md) [post]
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
- Deploying Astro SSR to a VPS with Podman Moving the Astro SSR container to a fresh Debian VPS: Podman from the distro packages, a read-only deploy key and the same compose file.
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
- Updating the Website Repository on a VPS A repeatable update flow on the VPS: check the working tree, pull with --ff-only, rebuild with podman-compose, verify, roll back, all in one script.