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.
Reviewed by adrian
on
Once my old site was running on the VPS, I wanted updates to be dull: the same commands every time, in the same order. This is the flow I settled on: pull, rebuild, verify, and a way back for the days it goes wrong.
The setup
- VPS: Debian, the project checked out at
/opt/website. - Runtime:
podman-composemanages the container, Caddy sits in front as reverse proxy. - Branches:
mainis production. Deploys pull on the server.
Check the state first
Before pulling, I look at the working tree. A dirty repository on the server means someone did something nobody should have done, and I want to catch that.
cd /opt/website
git status
git branch --show-current
git remote -v
If there are local changes anyway, stash them before the pull:
git stash push -m "vps-local-before-update"
Pull the latest code
cd /opt/website
git fetch --all --prune
git pull --ff-only origin main
--ff-only is the flag that matters. If anyone ever committed directly on the server, it prevents a merge commit there. Fast-forward or fail, no silent merges.
Rebuild and restart
cd /opt/website
podman-compose -f compose.yml down
podman-compose -f compose.yml up --build -d
Or in one go:
podman-compose -f compose.yml up --build -d --force-recreate
The most common hiccup is "container name already in use". compose.yml pins container_name: website, and an earlier run left a stopped container behind. Two ways out, depending on the mess:
# Option A: clean compose state
podman-compose -f compose.yml down
podman-compose -f compose.yml up --build -d
# Option B: remove the conflicting container explicitly
podman rm -f website
podman-compose -f compose.yml up --build -d
Option A is the normal move. Option B is for when down does not clean up properly.
Verify
Four checks, from local to public:
podman ps
podman logs --tail=100 website
curl -I http://127.0.0.1:4321
curl -I https://adrian-altner.de
The public HTTPS check is the final signal. Everything before it only says the container is alive, not that the reverse proxy still routes to it.
Roll back fast
When a deploy breaks production, restoring the service comes before finding the cause. Look at the history, check out the last good commit, rebuild:
cd /opt/website
git log --oneline -n 5
git checkout <previous-commit>
podman-compose -f compose.yml up --build -d
Then fix the bug on the laptop and deploy forward again from main. The server should not sit on a detached HEAD for long.
One script for all of it
#!/usr/bin/env bash
set -euo pipefail
cd /opt/website
git fetch --all --prune
git pull --ff-only origin main
if ! podman-compose -f compose.yml up --build -d; then
podman rm -f website || true
podman-compose -f compose.yml up --build -d
fi
curl -fsS -I http://127.0.0.1:4321 >/dev/null
echo "Deploy successful"
Saved as deploy.sh:
chmod +x deploy.sh
./deploy.sh
The fallback retries once after removing the stale container, without aborting the script. I later used the same pattern in Triggering VPS Deploys with GitHub Actions.
Takeaways
- If
git statuson the VPS is ever dirty, something is wrong before this flow even starts. - Only
curlagainst the public URL proves that Caddy still routes correctly. - Keep the rollback rehearsed:
git log,git checkout <sha>, rebuild.
Based on
-
Updating the Website Repository on a VPS
(
raw/2026/2026-03-04/updating-the-website-repository-on-a-vps.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.
Basis for
- Triggering VPS Deploys with GitHub Actions A GitHub Actions workflow that opens an SSH session to the VPS on every push to main and lets the server pull and rebuild itself.
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.
- Obsidian to VPS Pipeline: Sync, Pull and Redeploy One shell script on the Mac that pulls the site repository on the VPS, rsyncs the posts from the Obsidian vault and rebuilds the Astro container.
- 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.
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.