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.

I wanted a local stack for my old Astro site that looked exactly like production, so nothing would work on my laptop and then fail on the server. So I ran the site in Podman from day one, locally, with the Node standalone adapter doing the server-side rendering. This guide covers the first half: Astro rendering on the server and running in a container on my Mac. It was the start of a series; the later steps are listed at the end.

The setup

  • Astro in SSR mode via @astrojs/node in standalone mode.
  • Container entry point: dist/server/entry.mjs.
  • Runtime: Podman on macOS, the app on port 4321.

Astro SSR configuration

The Node adapter in standalone mode ships a small HTTP server of its own, with no Express and no extra glue. Together with output: "server" the build boots from a single JS file.

// astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import node from '@astrojs/node';

export default defineConfig({
    site: 'https://adrian-altner.de',
    output: 'server',
    integrations: [mdx()],
    markdown: {
        shikiConfig: {
            theme: 'github-light',
        },
    },
    adapter: node({
        mode: 'standalone',
    }),
});

A matching start script in package.json keeps the container command honest:

{
    "scripts": {
        "build": "astro build",
        "start": "node dist/server/entry.mjs"
    }
}

A two-stage Containerfile

The runtime image should carry only what serving the site needs: no dev dependencies, no source tree, no build tools. The first stage installs with pnpm and runs astro build. The second copies only dist/ into a slim Node image and drops privileges to the node user.

FROM node:20-bookworm-slim AS build

WORKDIR /app

COPY package.json pnpm-lock.yaml ./
RUN corepack enable && pnpm install --frozen-lockfile

COPY . .
RUN pnpm run build

FROM node:20-bookworm-slim AS runtime

WORKDIR /app

ENV NODE_ENV=production
ENV HOST=0.0.0.0
ENV PORT=4321

COPY --from=build --chown=node:node /app/dist ./dist

USER node

EXPOSE 4321

CMD ["node", "dist/server/entry.mjs"]

The runtime image holds nothing but dist/ and a Node interpreter. Boot time is mostly Node itself.

As of November 2026, Node 20 is past its end of life (30 April 2026); the current LTS lines are 22, 24 and 26.1 Corepack ships with Node up to version 24 only. From Node 25 on, corepack enable needs a separate npm install -g corepack first.2

The compose file

Compose is more than a single service needs. It makes the local and the production call identical, though: same file, same command.

# compose.yml
services:
  website:
    build:
      context: .
      dockerfile: Containerfile
    container_name: website
    ports:
      - '4321:4321'
    environment:
      NODE_ENV: production
      HOST: 0.0.0.0
      PORT: 4321
    restart: unless-stopped

Running it locally

podman machine start
podman compose -f compose.yml up --build -d
podman ps
curl -I http://localhost:4321

An HTTP/1.1 200 OK from the last curl was the whole acceptance test at this stage.

Two problems on the first boot

  • Wrong compose provider. If podman compose quietly calls docker-compose, pin the provider: export PODMAN_COMPOSE_PROVIDER=/opt/homebrew/bin/podman-compose.
  • The VM hangs on startup. podman machine stop && podman machine start clears it.

The rest of the series

Takeaways

  • Run the same container locally that you intend to ship. The packaging is the spec.
  • Check early that dist/server/entry.mjs boots. Once that path is stable, the rest is plumbing.

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
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 →