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/nodeinstandalonemode. - 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 composequietly callsdocker-compose, pin the provider:export PODMAN_COMPOSE_PROVIDER=/opt/homebrew/bin/podman-compose. - The VM hangs on startup.
podman machine stop && podman machine startclears it.
The rest of the series
- Deploying Astro SSR to a VPS with Podman: the same container on a Debian VPS.
- Caddy as Reverse Proxy with HTTPS and a Canonical Host: HTTPS in front of the container.
- GitHub Deploy Key on a VPS and Installing Podman Locally and on a VPS.
- Updating the Website Repository on a VPS and Operating Astro SSR in Production with Podman.
- Keeping a Compose Stack Running After a Reboot.
- Triggering VPS Deploys with GitHub Actions.
Takeaways
- Run the same container locally that you intend to ship. The packaging is the spec.
- Check early that
dist/server/entry.mjsboots. Once that path is stable, the rest is plumbing.
- 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
-
- 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.
- Uses
- 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.
- Installing Podman Locally and on a VPS Podman with podman-compose on macOS and on a Debian or Ubuntu server, with the same commands on both sides and a first-run check.
- Keeping a Compose Stack Running After a Reboot A systemd unit that starts a Podman compose stack on boot, so a website comes back by itself after the VPS restarts.
- 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.
- Triggering VPS Deploys with GitHub Actions A GitHub Actions workflow that opens an SSH session to the VPS on every push to main and lets the server pull and rebuild itself.
- 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.
- Tags