Docker-Build

Der Builder wird als Docker-Image ausgeliefert. Content-Repositories verwenden ihn, um statisches HTML zu erzeugen, ohne Node.js oder Astro lokal installieren zu müssen.

Dockerfile

docker/Dockerfile verwendet einen mehrstufigen Build auf Basis von node:24-alpine:

FROM node:24-alpine AS builder
WORKDIR /app

# Install deps (cached layer)
COPY package*.json ./
RUN npm ci

# Copy framework code
COPY . .

# Remove placeholder content
RUN rm -rf src/content/docs/*

COPY docker/entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh

ENTRYPOINT ["/entrypoint.sh"]

Schichtenstrategie

Schicht	Inhalt	Warum separat gecacht
1	COPY package*.json + npm ci	Abhängigkeiten ändern sich selten; das Caching dieser Schicht vermeidet erneutes Herunterladen bei jedem Build
2	COPY . .	Framework-Quellcode
3	rm -rf src/content/docs/*	Bereinigt Platzhalter-Inhalte, damit nur eingespeister Content erscheint
4	COPY entrypoint.sh	Build-Orchestrierungsskript

Entrypoint

docker/entrypoint.sh wird bei jedem Containerstart ausgeführt. Es führt die folgenden Schritte der Reihe nach aus:

Schritt 1: Abhängigkeiten aktualisieren

npm install
npm update

Stellt sicher, dass das Theme-Paket und alle Abhängigkeiten auf ihren neuesten kompatiblen Versionen sind.

Schritt 2: Theme-Konfiguration kopieren

cp /app/node_modules/@f5-sales-demo/docs-theme/astro.config.mjs /app/astro.config.mjs
cp /app/node_modules/@f5-sales-demo/docs-theme/src/content.config.ts /app/src/content.config.ts

Kopiert astro.config.mjs und content.config.ts aus dem Theme-Paket. Das Theme ist die einzige Quelle der Wahrheit für die Astro-Konfiguration — siehe Architektur für das Design des Theme-Systems.

Schritt 3: Inhalte einspeisen

if [ -d "$CONTENT_DIR" ]; then
  cp -r "$CONTENT_DIR"/* /app/src/content/docs/
else
  echo "ERROR: No content found at $CONTENT_DIR"
  exit 1
fi

Kopiert die gemounteten Inhalte in das Content-Collection-Verzeichnis von Astro. Beendet sich mit einem Fehler, wenn das Content-Verzeichnis fehlt.

Schritt 4: Titel extrahieren

if [ -z "$DOCS_TITLE" ] && [ -f /app/src/content/docs/index.mdx ]; then
  DOCS_TITLE=$(grep -m1 '^title:' /app/src/content/docs/index.mdx | sed 's/title: *["]*//;s/["]*$//')
  export DOCS_TITLE
fi

Falls DOCS_TITLE nicht über eine Umgebungsvariable gesetzt ist, wird er aus dem title:-Frontmatter-Feld von index.mdx extrahiert.

Schritt 5: Basispfad extrahieren

if [ -z "$DOCS_BASE" ] && [ -n "$GITHUB_REPOSITORY" ]; then
  DOCS_BASE="/${GITHUB_REPOSITORY#*/}"
  export DOCS_BASE
fi

Leitet den Basispfad der Website aus dem GitHub-Repository-Namen ab (z. B. wird owner/my-docs zu /my-docs).

Schritt 6: Build

npm run build

Führt astro build aus und erzeugt statische Ausgabe in /app/dist/.

Schritt 7: Ausgabe kopieren

if [ -d "$OUTPUT_DIR" ]; then
  cp -r /app/dist/* "$OUTPUT_DIR"/
fi

Kopiert die erstellte Website zum Ausgabe-Mount-Punkt.

Umgebungsvariablen

Variable	Standard	Beschreibung
CONTENT_DIR	/content/docs	Pfad zum gemounteten Content-Verzeichnis
OUTPUT_DIR	/output	Pfad, in den die erstellte Website kopiert wird
DOCS_TITLE	(aus index.mdx extrahiert)	Website-Titel, der an die Astro-Konfiguration übergeben wird
DOCS_DESCRIPTION	(aus index.mdx extrahiert)	Website-Beschreibung aus dem Frontmatter
DOCS_BASE	(abgeleitet von GITHUB_REPOSITORY)	Basispfad für die Website (z. B. /my-docs)
DOCS_SITE	(abgeleitet von GITHUB_REPOSITORY_OWNER)	Website-URL, die an die Astro-Konfiguration übergeben wird (z. B. https://<owner>.github.io)
GITHUB_REPOSITORY	(von GitHub Actions gesetzt)	owner/repo-Zeichenkette, die zur Ableitung von DOCS_BASE verwendet wird
GENERATE_PDF	false	PDF-Generierung nach dem Build aktivieren
PDF_FILENAME	docs	Ausgabedateiname für das generierte PDF
LLMS_OPTIONAL_LINKS	[]	JSON-Array von Child-Site-URLs für den “Optional”-Abschnitt in llms.txt

Lokale Nutzung

Um Dokumentation lokal mit Docker zu erstellen:

docker run --rm \
  -v "$(pwd)/docs:/content/docs" \
  -v "$(pwd)/output:/output" \
  ghcr.io/f5-sales-demo/docs-builder:latest

Dies mountet das lokale docs/-Verzeichnis als Content und schreibt die erstellte Website nach output/.

Für Content-Autoren, die einen Live-Entwicklungsserver-Workflow wünschen, siehe Lokale Vorschau für Content-Autoren.

Entwickler: Lokaler Entwicklungsserver

Wenn Sie am Builder selbst arbeiten (Komponenten, Plugins, Theme-Integration), können Sie Astros Entwicklungsserver direkt ohne Docker ausführen:

npm ci
cp node_modules/@f5-sales-demo/docs-theme/astro.config.mjs astro.config.mjs
cp node_modules/@f5-sales-demo/docs-theme/src/content.config.ts src/content.config.ts
# Copy some test content into the content collection
cp -r /path/to/test-content/* src/content/docs/
DOCS_TITLE="Dev Test" npx astro dev --host

Öffnen Sie http://localhost:4321. Hot Module Replacement (HMR) funktioniert für Komponenten- und Plugin-Änderungen.

Hinweis

astro.config.mjs und content.config.ts stammen aus dem Theme-Paket und werden in diesem Repository nicht versioniert. Sie müssen sie aus node_modules kopieren, bevor Sie den Entwicklungsserver starten. Der Entrypoint erledigt dies bei Docker-Builds automatisch.

Hinweis

src/content/docs/ wird beim Image-Build geleert und ist in der Gitignore-Datei eingetragen. Platzieren Sie Testinhalte dort manuell — sie werden nicht committet.

Image-Registry

Das Image wird in der GitHub Container Registry veröffentlicht:

ghcr.io/f5-sales-demo/docs-builder

Bei jedem Build werden zwei Tags gepusht:

Tag	Beschreibung
latest	Neuester Build von main
<sha>	Vollständiger Git-Commit-SHA für reproduzierbare Builds

Siehe CI/CD und Governance für den Workflow, der das Image baut und veröffentlicht.