Deployment

Deployment

AstroPaper builds to a fully static site (HTML, CSS, JS, and assets). You can host it anywhere that serves static files.

Table of Contents

• Before deploying
• Vercel
• Netlify
• GitHub Pages
• Cloudflare Pages
• Docker

Before Deploying

1. Set site.url in astro-paper.config.ts to your deployed URL (e.g. "https://myblog.com/"). This is used for canonical URLs, the sitemap, the RSS feed, and OG image URLs.

2. Run pnpm build locally to verify the build succeeds.

3. Run pnpm preview to smoke-test the production build before deploying.

Vercel

Vercel is the recommended deployment platform and is used for the official demo.

Via Vercel dashboard:

1. Import your repository on vercel.com
2. Vercel auto-detects Astro and sets the build command to astro build
3. Override the build command to pnpm build so Pagefind indexing runs after the Astro build
4. Deploy

Via Vercel CLI:

npm i -g vercel
vercel

vercel.json (optional override):

{
  "buildCommand": "pnpm build",
  "outputDirectory": "dist"
}

Netlify

1. Import your repository on netlify.com
2. Set the build command to pnpm build
3. Set the publish directory to dist
4. Deploy

netlify.toml (recommended):

[build]
  command = "pnpm build"
  publish = "dist"

GitHub Pages

GitHub Pages requires setting a base path if the site is served from a subdirectory (e.g. https://username.github.io/repo-name/).

1. Update astro.config.ts:

export default defineConfig({
  site: "https://username.github.io",
  base: "/repo-name",
  // ...
});

2. Add a GitHub Actions workflow (.github/workflows/deploy.yml):

name: Deploy to GitHub Pages
on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v3
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install
      - run: pnpm build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/deploy-pages@v4
        id: deployment

3. In your repository settings, go to Pages → Source → select GitHub Actions.

The base path setting also affects all internal links. AstroPaper's withBase utility handles this automatically.

Cloudflare Pages

1. Create a new Pages project and connect your repository
2. Set the build command to pnpm build
3. Set the build output directory to dist
4. Deploy

Docker

AstroPaper includes a Dockerfile for containerized deployment. It uses a two-stage build:

1. Build stage — installs dependencies and runs pnpm build
2. Runtime stage — serves the static files with nginx

# Base stage
FROM node:lts AS base
WORKDIR /app
RUN corepack enable && corepack prepare pnpm@latest --activate
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm run build

# Runtime stage
FROM nginx:mainline-alpine-slim AS runtime
COPY --from=base /app/dist /usr/share/nginx/html
EXPOSE 80

Build and run:

docker build -t astro-paper .
docker run -p 8080:80 astro-paper

The site will be available at http://localhost:8080.

With Docker Compose (compose.yaml is included):

docker compose up