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.

Article Created Updated

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-compose manages the container, Caddy sits in front as reverse proxy.
  • Branches: main is 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 status on the VPS is ever dirty, something is wrong before this flow even starts.
  • Only curl against 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]

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.

Basis for

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