Deploy Astro Starlight on Docker

This guide documents the deployment of this documentation site at docs.example.com using Astro Starlight, Docker, and Traefik.

Tested With

Astro 6.0.6
Starlight 0.38.1
Node 22
Express 4.x

Last updated: 19.mar.2026

Prerequisites

Debian server with Docker and Docker Compose installed
Traefik reverse proxy running
DNS A record pointing to your server IP

Architecture

┌─────────────────┐
│   Traefik       │  Port 80/443
│   (reverse      │  SSL via Let's Encrypt
│    proxy)       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ node:22-alpine  │  Express serves static files
│ + Express       │  dist/ baked into image
└─────────────────┘

Project Structure

/opt/docker/docs/
├── compose.yaml           # Express container config
├── Dockerfile             # Builds custom image with dist/
├── server.js              # Express static file server
├── build.sh               # docker run node:22-alpine build
├── package.json
├── astro.config.mjs
├── src/
│   ├── content.config.ts
│   └── content/docs/
│       └── *.mdx
├── public/
│   └── downloads/
└── dist/                  # generated static site

Step 1 - Create DNS Record

Add an A record pointing to your server:

Type: A
Name: docs
Value: <your_server_ip>

Verify DNS propagation:

dig +short docs.<your_domain>.com A

Step 2 - Create Directory Structure

mkdir -p /opt/docker/docs/src/content/docs
mkdir -p /opt/docker/docs/public/downloads

Step 3 - Create package.json

Create /opt/docker/docs/package.json:

{
  "name": "astro-docs-debian",
  "type": "module",
  "version": "0.0.1",
  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "astro": "astro"
  },
  "dependencies": {
    "astro": "^6.0.0",
    "@astrojs/starlight": "^0.38.0"
  }
}

Step 4 - Create astro.config.mjs

Create /opt/docker/docs/astro.config.mjs:

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  site: 'https://docs.<your_domain>.com',
  integrations: [
    starlight({
      title: 'Astro docs on Debian',
    }),
  ],
});

Step 5 - Create Content Config

Create /opt/docker/docs/src/content.config.ts:

import { defineCollection } from 'astro:content';
import { docsLoader } from '@astrojs/starlight/loaders';
import { schema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({ loader: docsLoader(), schema }),
};

Step 6 - Create Build Script

Create /opt/docker/docs/build.sh:

#!/bin/sh
docker run --rm \
  -v "$(dirname "$0")":/app \
  -w /app \
  node:22-alpine \
  sh -c "npm install && npm run build"

Make it executable:

chmod +x /opt/docker/docs/build.sh

Step 7 - Create Index Page

Create /opt/docker/docs/src/content/docs/index.mdx:

---
title: Your Site Title
description: Site description
---

Welcome to the documentation.

Step 8 - Build the Site

cd /opt/docker/docs
./build.sh

This pulls node:22-alpine and generates the dist/ folder.

Step 9 - Create Dockerfile

Create /opt/docker/docs/Dockerfile:

FROM node:22-alpine

WORKDIR /app

RUN npm install express && echo '{"type":"module"}' > package.json

COPY dist ./dist
COPY server.js .

EXPOSE 4322

CMD ["node", "server.js"]

Step 10 - Create Express Server

Create /opt/docker/docs/server.js:

import express from 'express';
import { fileURLToPath } from 'url';
import { dirname, join } from 'path';
import fs from 'fs';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

const app = express();
const port = process.env.PORT || 4322;

app.use(express.static(join(__dirname, 'dist')));

app.use((req, res) => {
  const htmlPath = join(__dirname, 'dist', req.path + '.html');
  const indexPath = join(__dirname, 'dist', 'index.html');

  if (fs.existsSync(htmlPath)) {
    res.sendFile(htmlPath);
  } else {
    res.sendFile(indexPath);
  }
});

app.listen(port, '0.0.0.0', () => {
  console.log(`Docs server running on port ${port}`);
});

Step 11 - Create Docker Compose

Create /opt/docker/docs/compose.yaml:

services:
  docs:
    build: .
    image: docs-starlight
    container_name: docs
    restart: unless-stopped
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.docs.rule=Host(`docs.<your_domain>.com`)"
      - "traefik.http.routers.docs.entrypoints=websecure"
      - "traefik.http.routers.docs.tls.certresolver=letsencrypt"
      - "traefik.http.services.docs.loadbalancer.server.port=4322"
    networks:
      - proxy
    deploy:
      resources:
        limits:
          memory: 128M

networks:
  proxy:
    external: true

Step 12 - Start the Container

cd /opt/docker/docs
docker compose up -d

Step 13 - Verify

Visit https://docs.<your_domain>.com in your browser.

Adding New Content

Create new .mdx file in src/content/docs/
Run ./build.sh

Rebuild and restart container:

docker compose build --no-cache && docker compose up -d

Adding Downloadable Files

Copy files to public/downloads/
Run ./build.sh