Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 37 ยท Performance and Deployment

Deploying an Astro Site: Static Hosts, Node and Docker

Deploy Astro to static hosts, GitHub Pages and Node or Docker servers. Learn site and base settings, build commands, environment variables and CI checks.

You have built the site. Now you need to put it on the internet. Because Astro outputs either plain files (static) or a small Node-style server (SSR), there are many hosting options. This lesson walks through the build, the settings that must be right for URLs, and deployment recipes for common platforms.

Build and preview

Terminal
npm run build      # astro build, writes ./dist
npm run preview    # astro preview, serves the build locally
  • Static output: dist/ contains HTML, CSS, JS and assets. Upload that folder anywhere.
  • Server output: dist/client/ holds static assets and dist/server/ the server entry; you deploy both, usually through the adapter's platform integration.

Always run astro preview before shipping. It serves the production build, which behaves differently from astro dev (no hot reload, hashed assets, real prerendering). astro preview is a check tool, not a production server.

Also run npx astro check (needs @astrojs/check and typescript) to type-check .astro files in CI.

The two settings that break URLs: site and base

JavaScript
// astro.config.mjs
export default defineConfig({
  site: 'https://example.com',
  base: '/docs',        // only if the site lives under a subpath
  trailingSlash: 'always',
});
  • site is the full production origin. Sitemaps, RSS, canonical links and Astro.site use it.
  • base is a path prefix. Everything Astro generates (assets, routes) lives under it, and you must write your own links with import.meta.env.BASE_URL:
ASTRO
<a href={`${import.meta.env.BASE_URL}about/`}>About</a>
  • trailingSlash: pick one (always or never) and keep it. Mixed styles cause duplicate-URL problems and redirect loops on some hosts.

GitHub project pages are a classic: a repo me/blog publishes at https://me.github.io/blog/, so you need site: 'https://me.github.io' and base: '/blog'.

Static hosts

Netlify, Vercel, Cloudflare Pages

All three work the same way: connect your Git repository and set

  • Build command: npm run build
  • Output directory: dist
  • Node version: matching your local one (set NODE_VERSION or an .nvmrc)

Every push builds a preview deployment with its own URL, and merging to main updates production. Add environment variables in the dashboard. A public/_redirects (Netlify, Cloudflare) or the redirects option in astro.config.mjs handles moved URLs:

JavaScript
redirects: {
  '/old-post': '/blog/new-post',
  '/news/[slug]': '/blog/[slug]',
}

For SSR on these platforms, add the matching adapter (@astrojs/netlify, vercel or cloudflare) and the platform builds functions for you.

GitHub Pages

Create .github/workflows/deploy.yml:

YAML
name: Deploy to GitHub Pages
on:
  push:
    branches: [main]
permissions:
  contents: read
  pages: write
  id-token: write
concurrency:
  group: pages
  cancel-in-progress: true
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22, cache: npm }
      - run: npm ci
      - run: npx astro check
      - run: npm run 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:
      - id: deployment
        uses: actions/deploy-pages@v4

Set Pages source to "GitHub Actions" in the repo settings. Remember the site and base values above.

A Node server and Docker

For SSR with @astrojs/node in standalone mode:

DOCKERFILE
FROM node:22-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:22-alpine
WORKDIR /app
ENV HOST=0.0.0.0 PORT=4321 NODE_ENV=production
COPY --from=build /app/dist ./dist
COPY --from=build /app/node_modules ./node_modules
EXPOSE 4321
USER node
CMD ["node", "./dist/server/entry.mjs"]

Put the container behind a reverse proxy (Caddy, nginx, a platform load balancer) that terminates HTTPS and sends compression and cache headers. Add a health check endpoint such as /healthz that returns ok. Pass secrets as runtime environment variables, never by baking them into the image.

Environment variables in deployment

  • Build-time variables (PUBLIC_* and anything read during prerendering) must exist during the build.
  • Runtime variables for SSR must exist in the running environment.
  • Keep a .env.example in the repo listing names without values; keep .env in .gitignore.

Pre-launch checklist

  1. site is the final origin; base and trailingSlash are decided.
  2. 404 page exists (src/pages/404.astro) and the host serves it.
  3. robots.txt, sitemap and canonical tags are correct.
  4. Redirects are in place for any old URLs.
  5. HTTPS only, with redirect from HTTP and from www to your canonical host.
  6. Caching headers set (hashed assets immutable).
  7. Lighthouse run on the live URL.
  8. Error monitoring and analytics added (lightweight, loaded late).
  9. A rollback plan: platforms keep previous deployments, so rolling back is one click.

Try it: URL builder with site, base and trailing slash

A frequent deployment bug is wrong links under a base path. This stand-in builds URLs the way a careful helper would.

JS site, base and trailingSlash

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Try it: a pre-launch audit

This stand-in checks a config object for the mistakes that cause the most broken launches. You can reuse the idea in CI as a script reading your real config.

JS Config audit

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A GitHub project page is at https://me.github.io/blog/. Which config is right?

    site is the origin and base is the path prefix; internal links must also use BASE_URL.
  2. 2. What does astro preview do?

    It is a local check of the built output, not a production server.
  3. 3. When must PUBLIC_ and prerender-time variables be available?

    They are read while Astro builds pages and bundles client code, so the build environment needs them.
  4. 4. Which is NOT a good place for a database password?

    PUBLIC_ values are embedded in client code that anyone can read.

Summary

  • Build with astro build, verify with astro preview and astro check.
  • Set site, base and trailingSlash deliberately; use BASE_URL for links.
  • Static hosts need only the build command and dist; GitHub Pages uses a workflow; SSR needs an adapter or a Node container.
  • Keep secrets out of the repo and out of PUBLIC_ variables.
  • Run a launch checklist: 404, redirects, HTTPS, caching, sitemap, Lighthouse.

Next: Project: A Blog with Content Collections