Keeping a Compose Stack Running After a Reboot
A systemd unit that starts a Podman compose stack on boot, so a website comes back by itself after the VPS restarts.
Reviewed by adrian
on
The first time the VPS rebooted for a kernel update, the site stayed down until I SSH'd in and ran podman-compose up -d by hand. That's the kind of thing you only accept once. A deployment that survives its own runtime but not the box underneath it isn't really production. This is the minimal systemd wiring that makes a reboot a non-event.
The setup
- VPS: Debian, Podman running rootful, compose stack under
/opt/website. - Reverse proxy: Caddy in front of the app container.
- Goal: after
sudo reboot, everything is back on its own: container, Caddy, TLS.
Restart policy in Compose
Inside compose.yml:
restart: unless-stopped
This is necessary but not enough. It tells Podman to restart the container if it crashes, but after a full reboot nobody runs podman-compose up in the first place, so nothing tells Podman about this compose stack at all. A systemd unit has to own the compose lifecycle.
A systemd service for the compose stack
/etc/systemd/system/website-compose.service:
[Unit]
Description=Website Podman Compose Stack
After=network-online.target
Wants=network-online.target
[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/opt/website
ExecStart=/usr/bin/podman-compose -f compose.yml up -d
ExecStop=/usr/bin/podman-compose -f compose.yml down
TimeoutStartSec=0
[Install]
WantedBy=multi-user.target
Two details matter:
Type=oneshotwithRemainAfterExit=yes:podman-compose up -dreturns right after starting the container, so systemd sees it exit.RemainAfterExittells systemd to keep the unit "active" afterwards.After=network-online.target: without it, the compose stack can race the network on a cold boot and fail to pull or resolve anything. Such failures look random and are hard to debug later.
Enable and start it:
sudo systemctl daemon-reload
sudo systemctl enable website-compose.service
sudo systemctl start website-compose.service
sudo systemctl status website-compose.service --no-pager
Make sure Caddy also starts on boot
Caddy's Debian package enables its unit by default, but it's worth confirming instead of assuming:
sudo systemctl enable caddy
sudo systemctl status caddy --no-pager
The reboot test
The only way to know the wiring is right is to actually reboot the machine:
sudo reboot
After reconnecting over SSH:
systemctl status website-compose.service --no-pager
podman ps
curl -I http://127.0.0.1:4321
curl -I https://adrian-altner.de
What I expect to see:
website-compose.serviceactive.- The website container running.
- Both the local and the public check return
200.
Troubleshooting after a reboot
- Container not running. Logs first, always:
journalctl -u website-compose.service -n 100 --no-pager - Caddy up but site down. The app container is the usual suspect:
podman logs --tail=200 website - TLS or proxy issues. Caddy's journal says which hostname failed and why:
journalctl -u caddy -n 100 --no-pager
Takeaways
restart: unless-stoppedcovers crashes, systemd covers reboots. You need both.- Reboot the machine on purpose, once, before you ever need to trust the setup unattended.
Based on
-
Keeping the Website Running After a VPS Reboot
(
raw/2026/2026-03-04/keeping-the-website-running-after-a-vps-reboot.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
- Installing Podman Locally and on a VPS Podman with podman-compose on macOS and on a Debian or Ubuntu server, with the same commands on both sides and a first-run check.
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.
Mentioned
- Caddy as Reverse Proxy with HTTPS and a Canonical Host Caddy in front of a container on a VPS: automatic TLS from Let's Encrypt, www redirected to the bare domain, the app port closed to the outside.