Deploy guide · runtime = "docker"

Deploy Astro on Percher

Astro is a content-first framework that ships zero JS by default and adds it per-island. Pages can be static (no server) or SSR via an adapter. Percher handles both shapes — static Astro through a multi-stage Docker build, SSR Astro through the Node runtime with `@astrojs/node`.

Why Percher fits

• Static Astro ships as a slim Caddy-served container (multi-stage build: Bun compiles, Alpine+Caddy serves). Cold start is essentially instant.
• SSR Astro with `@astrojs/node` runs on the same Node pipeline Next.js and SvelteKit use — fast cold builds and predictable behaviour.

Quick start

bunx percher create my-app --template astro
cd my-app
bunx percher publish

The first command scaffolds a working Astro project plus a `percher.toml`. Publish builds and deploys it; the live URL prints on completion.

percher.toml

The canonical config for a Astro app on Percher. `bunx percher init` generates this automatically when it detects Astro in your project.

# Static Astro (no @astrojs/node adapter)
[app]
name = "my-site"
runtime = "docker"
framework = "astro"

[web]
port = 8080
health = "/"

Common gotchas

• Static Astro needs `runtime = "docker"` plus a generated `Dockerfile` + `Caddyfile`. `bunx percher init` scaffolds both automatically when it detects Astro without the Node adapter.
• SSR Astro needs `@astrojs/node` installed and configured (`output: "server"` in `astro.config.mjs`) — use the SSR percher.toml shape (`runtime = "node"`, `port = 4321`) instead.
• Auto-forwards both `PUBLIC_*` (Astro server) and `VITE_*` (Astro client) env vars; pick the one matching where you read it.

Related docs

• Recommended setup →
• Environment variables →

Ready to deploy Astro?

Free plan, no credit card. Live in under a minute.