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.

Article Created Updated

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-compose from 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.yml moves 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_PROVIDER on 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]

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

  • 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

Show in the graph view