Deploy Astro Starlight on Docker

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

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)       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   nginx:alpine  │  Serves static files
│   (docs)        │  from /dist
└─────────────────┘

Project Structure

/opt/docker/docs/
├── compose.yaml           # nginx serving dist/
├── 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 Docker Compose

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

services:
  docs:
    image: nginx:alpine
    container_name: docs
    restart: unless-stopped
    volumes:
      - ./dist:/usr/share/nginx/html:ro
    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=80"
    networks:
      - proxy
    deploy:
      resources:
        limits:
          memory: 64M

networks:
  proxy:
    external: true

Step 10 - Start the Container

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

Step 11 - Verify

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

Adding New Content

Create new .mdx file in src/content/docs/
Run ./build.sh
nginx serves updated content automatically

Adding Downloadable Files

Copy files to public/downloads/
Run ./build.sh
Link to files: /downloads/filename.ext

Troubleshooting

Build fails with content config error

Astro 6 requires src/content.config.ts (not src/content/config.ts). Ensure you’re using the new format with docsLoader().

404 errors

Verify dist/ folder exists and contains index.html.

SSL certificate issues

Check Traefik logs:

docker logs traefik

Ensure DNS is properly configured and propagating.