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.
Reviewed by adrian
on
With the Astro SSR container running on my laptop (local setup), I wanted it on the VPS without a new set of commands for production. Same compose file, same entry point, different host. This is the path that worked on a fresh Debian VPS.
The setup
- VPS: Debian, freshly provisioned, SSH access as a non-root user.
- Runtime: Podman and
podman-composefrom the distro packages. - Source of truth: the Git repository, cloned into
/opt/website.
Install the tools
sudo apt-get update
sudo apt-get -y install podman podman-compose git
The distro packages are recent enough for a single-container app.
Clone the repository with a deploy key
My first git clone over HTTPS failed at once:
Invalid username or token. Password authentication is not supported
GitHub dropped password authentication years ago, and the VPS had no credential helper. Instead of pasting a personal access token onto the server, I switched to SSH with a key:
mkdir -p ~/.ssh && chmod 700 ~/.ssh
ssh-keygen -t ed25519 -C "vps-website" -f ~/.ssh/id_ed25519 -N ""
cat ~/.ssh/id_ed25519.pub
The public key went into the repository's Deploy Keys: read-only, for this one repository. GitHub Deploy Key on a VPS covers this step in more detail.
ssh-keyscan github.com >> ~/.ssh/known_hosts
git clone [email protected]:adrian-altner/website.git /opt/website
From then on git pull worked unattended: no token expiry, no prompts, no shared account credentials on the server.
Start the app
cd /opt/website
podman-compose -f compose.yml up --build -d
Three checks: the container is up, the logs show Astro booting, the local port answers.
podman ps
podman logs -f website
curl -I http://127.0.0.1:4321
A 200 from the last one means the app is healthy. It still only listens on localhost; Caddy came next.
Problems I ran into
Docker Hub auth errors on the first build. The first pull failed with this, even for public images:
unable to retrieve auth token: invalid username/password
Pulling the base image once by hand cleared whatever stale state Podman was carrying:
podman pull docker.io/library/node:20-bookworm-slim
After that, podman-compose up --build -d went through. Node 20 reached its end of life on 30 April 2026; for a new setup, pull the image of a current LTS line instead (as of November 2026: Node 24 or 26).1
Compose provider warnings. When Podman announced it was falling back to an external docker-compose, installing and pinning podman-compose settled it:
sudo apt-get -y install podman-compose
export PODMAN_COMPOSE_PROVIDER=/usr/bin/podman-compose
From then on:
podman compose -f compose.yml up --build -d
Takeaways
- The local
compose.ymlmoves to the VPS unchanged. That is the point of running it locally first. - A mysterious failure on the first pull is most likely a stale Podman auth cache. Pull the base image once by hand.
- Pin
PODMAN_COMPOSE_PROVIDERon servers, so the command cannot change its behaviour under you.
Based on
-
Deploying Astro SSR to a VPS with Podman
(
raw/2026/2026-03-02/deploying-astro-ssr-to-a-vps-with-podman.md) [post] - Node.js end-of-life dates [node-eol]
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
- 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.
- 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.
Builds on
- 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.
Uses
- Astro Tool for building websites from content such as Markdown. Ships plain HTML by default and only loads JavaScript where it is needed.
- 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
- 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
- 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.
- GitHub Deploy Key on a VPS A read-only SSH deploy key so a VPS can pull from GitHub without a personal access token or a password.