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.

Article Created Updated Also in German: Einen Compose-Stack nach einem Neustart weiterlaufen lassen

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=oneshot with RemainAfterExit=yes: podman-compose up -d returns right after starting the container, so systemd sees it exit. RemainAfterExit tells 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.service active.
  • 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-stopped covers 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]

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

Mentioned

Show in the graph view