Deploying Astro SSR to a VPS with Podman

Category: On-Premises & Private Cloud

Tags: podman, deployment

With the Astro SSR container running cleanly on my laptop, I wanted to move it onto the VPS without inventing a new set of commands for production. The goal was a short, boring deploy sequence — the same compose file, the same entry point, just a different host.

This is the exact 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: a Git repository cloned into /opt/website.

Install runtime tools

sudo apt-get update
sudo apt-get -y install podman podman-compose git

Nothing exotic — the distro packages are modern enough for a single-container app.

Cloning the repository

Problem: My first git clone over HTTPS failed immediately with:

Invalid username or token. Password authentication is not supported

GitHub dropped password auth years ago, and the VPS had no credential helper configured. Rather than pasting a PAT onto the server, I switched to key-based SSH.

Implementation:

mkdir -p ~/.ssh && chmod 700 ~/.ssh
ssh-keygen -t ed25519 -C "vps-website" -f ~/.ssh/id_ed25519 -N ""
cat ~/.ssh/id_ed25519.pub

That public key went into the repository’s Deploy Keys — read-only, scoped to this one repo, nothing else.

ssh-keyscan github.com >> ~/.ssh/known_hosts
git clone git@github.com:adrian-altner/website.git /opt/website

Solution: git pull now works unattended — no PAT expiry, no prompts, no shared account credentials on the box.

Starting the app

cd /opt/website
podman-compose -f compose.yml up --build -d

Three quick 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 behind the scenes. It’s still on localhost only — Caddy comes in a later post.

The gotchas I hit

Docker Hub auth errors on first build. The initial pull can fail with:

unable to retrieve auth token: invalid username/password

Even with public images. Pulling the base image explicitly once clears whatever stale state Podman is carrying:

podman pull docker.io/library/node:20-bookworm-slim

After that, podman-compose up --build -d goes through cleanly.

Compose provider warnings. If Podman announces it’s falling back to an external docker-compose, installing and pinning podman-compose takes the ambiguity out:

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

What to take away

  • Key-based SSH with a Deploy Key beats HTTPS + PAT for unattended pulls — no expiry to manage.
  • The local compose.yml transfers to the VPS unchanged; that’s the whole point.
  • A stale Podman auth cache is the most likely cause of mysterious first-pull failures — pull the base image directly once to reset it.
  • Pin PODMAN_COMPOSE_PROVIDER explicitly on servers so the command can’t silently change behaviour under you.