Docker Build

Il builder viene distribuito come immagine Docker. I repository di contenuti lo eseguono per produrre HTML statico senza installare Node.js o Astro localmente.

Dockerfile

docker/Dockerfile utilizza un build multi-step basato su 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"]

Strategia dei Layer

Layer	Cosa	Perché viene cachato separatamente
1	COPY package*.json + npm ci	Le dipendenze cambiano raramente; il caching di questo layer evita di riscaricarle ad ogni build
2	COPY . .	Codice sorgente del framework
3	rm -rf src/content/docs/*	Rimuove qualsiasi contenuto placeholder in modo che appaia solo il contenuto iniettato
4	COPY entrypoint.sh	Script di orchestrazione della build

Entrypoint

docker/entrypoint.sh viene eseguito ogni volta che il container si avvia. Esegue questi passaggi in ordine:

Passaggio 1: Aggiornamento delle Dipendenze

npm install
npm update

Assicura che il pacchetto del tema e tutte le dipendenze siano alle ultime versioni compatibili.

Passaggio 2: Copia della Configurazione del Tema

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

Copia astro.config.mjs e content.config.ts dal pacchetto del tema. Il tema è l’unica fonte di verità per la configurazione di Astro — consulta Architettura per il design del sistema di temi.

Passaggio 3: Iniezione del Contenuto

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

Copia il contenuto montato nella directory della content collection di Astro. Esce con un errore se la directory del contenuto è mancante.

Passaggio 4: Estrazione del Titolo

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

Se DOCS_TITLE non è impostato tramite variabile d’ambiente, lo estrae dal campo frontmatter title: di index.mdx.

Passaggio 5: Estrazione del Base Path

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

Ricava il base path del sito dal nome del repository GitHub (ad esempio, owner/my-docs diventa /my-docs).

Passaggio 6: Build

npm run build

Esegue astro build, producendo l’output statico in /app/dist/.

Passaggio 7: Copia dell’Output

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

Copia il sito costruito nel punto di mount dell’output.

Variabili d’Ambiente

Variabile	Default	Descrizione
CONTENT_DIR	/content/docs	Percorso della directory del contenuto montata
OUTPUT_DIR	/output	Percorso dove viene copiato il sito costruito
DOCS_TITLE	(estratto da index.mdx)	Titolo del sito passato alla configurazione di Astro
DOCS_DESCRIPTION	(estratto da index.mdx)	Descrizione del sito dal frontmatter
DOCS_BASE	(derivato da GITHUB_REPOSITORY)	Base path per il sito (ad esempio, /my-docs)
DOCS_SITE	(derivato da GITHUB_REPOSITORY_OWNER)	URL del sito passato alla configurazione di Astro (ad esempio, https://<owner>.github.io)
GITHUB_REPOSITORY	(impostato da GitHub Actions)	Stringa owner/repo utilizzata per derivare DOCS_BASE
GENERATE_PDF	false	Abilita la generazione del PDF dopo la build
PDF_FILENAME	docs	Nome del file di output per il PDF generato
LLMS_OPTIONAL_LINKS	[]	Array JSON di URL di siti figlio per la sezione Optional di llms.txt

Utilizzo Locale

Per costruire la documentazione localmente utilizzando Docker:

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

Questo monta la directory locale docs/ come contenuto e scrive il sito costruito in output/.

Per gli autori di contenuti che desiderano un flusso di lavoro con dev server live, consulta Anteprima Locale per Autori di Contenuti.

Sviluppatore: Dev Server Locale

Quando si lavora sul builder stesso (componenti, plugin, integrazione del tema), è possibile eseguire il dev server di Astro direttamente senza Docker:

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

Apri http://localhost:4321. L’Hot Module Replacement (HMR) funziona per le modifiche a componenti e plugin.

Nota

astro.config.mjs e content.config.ts provengono dal pacchetto del tema e non sono versionati in questo repository. È necessario copiarli da node_modules prima di eseguire il dev server. L’entrypoint gestisce questa operazione automaticamente nelle build Docker.

Nota

src/content/docs/ viene svuotata al momento della build dell’immagine ed è presente nel gitignore. Inserisci manualmente il contenuto di test — non verrà committato.

Registro delle Immagini

L’immagine è pubblicata su GitHub Container Registry:

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

Due tag vengono pushati ad ogni build:

Tag	Descrizione
latest	Build più recente da main
<sha>	SHA completo del commit Git per build riproducibili

Consulta CI/CD e Governance per il workflow che costruisce e pubblica l’immagine.