Construcción con Docker

El constructor se distribuye como una imagen Docker. Los repositorios de contenido lo ejecutan para producir HTML estático sin necesidad de instalar Node.js o Astro localmente.

Dockerfile

docker/Dockerfile utiliza una construcción de múltiples pasos sobre 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"]

Estrategia de capas

Capa	Qué contiene	Por qué se cachea por separado
1	COPY package*.json + npm ci	Las dependencias cambian con poca frecuencia; cachear esta capa evita volver a descargarlas en cada construcción
2	COPY . .	Código fuente del framework
3	rm -rf src/content/docs/*	Limpia cualquier contenido de ejemplo para que solo aparezca el contenido inyectado
4	COPY entrypoint.sh	Script de orquestación de la construcción

Entrypoint

docker/entrypoint.sh se ejecuta cada vez que el contenedor inicia. Realiza los siguientes pasos en orden:

Paso 1: Actualizar dependencias

npm install
npm update

Asegura que el paquete del tema y todas las dependencias estén en sus últimas versiones compatibles.

Paso 2: Copiar la configuración 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 y content.config.ts desde el paquete del tema. El tema es la fuente única de verdad para la configuración de Astro — consulte Arquitectura para el diseño del sistema de temas.

Paso 3: Inyectar contenido

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 el contenido montado en el directorio de colecciones de contenido de Astro. Sale con un error si el directorio de contenido no existe.

Paso 4: Extraer el título

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

Si DOCS_TITLE no está definido a través de una variable de entorno, lo extrae del campo title: del frontmatter de index.mdx.

Paso 5: Extraer la ruta base

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

Deriva la ruta base del sitio a partir del nombre del repositorio de GitHub (por ejemplo, owner/my-docs se convierte en /my-docs).

Paso 6: Construir

npm run build

Ejecuta astro build, produciendo la salida estática en /app/dist/.

Paso 7: Copiar la salida

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

Copia el sitio construido al punto de montaje de salida.

Variables de entorno

Variable	Valor predeterminado	Descripción
CONTENT_DIR	/content/docs	Ruta al directorio de contenido montado
OUTPUT_DIR	/output	Ruta donde se copia el sitio construido
DOCS_TITLE	(extraído de index.mdx)	Título del sitio pasado a la configuración de Astro
DOCS_DESCRIPTION	(extraído de index.mdx)	Descripción del sitio desde el frontmatter
DOCS_BASE	(derivado de GITHUB_REPOSITORY)	Ruta base del sitio (por ejemplo, /my-docs)
DOCS_SITE	(derivado de GITHUB_REPOSITORY_OWNER)	URL del sitio pasada a la configuración de Astro (por ejemplo, https://<owner>.github.io)
GITHUB_REPOSITORY	(definido por GitHub Actions)	Cadena owner/repo utilizada para derivar DOCS_BASE
GENERATE_PDF	false	Habilitar la generación de PDF después de la construcción
PDF_FILENAME	docs	Nombre del archivo de salida para el PDF generado
LLMS_OPTIONAL_LINKS	[]	Array JSON de URLs de sitios secundarios para la sección Optional de llms.txt

Uso local

Para construir documentación localmente usando Docker:

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

Esto monta el directorio local docs/ como contenido y escribe el sitio construido en output/.

Para autores de contenido que deseen un flujo de trabajo con servidor de desarrollo en vivo, consulte Vista previa local para autores de contenido.

Desarrollador: Servidor de desarrollo local

Cuando se trabaja en el propio constructor (componentes, plugins, integración del tema), puede ejecutar el servidor de desarrollo de Astro directamente sin 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

Abra http://localhost:4321. El reemplazo de módulos en caliente (HMR) funciona para cambios en componentes y plugins.

Nota

astro.config.mjs y content.config.ts provienen del paquete del tema y no están bajo control de versiones en este repositorio. Debe copiarlos desde node_modules antes de ejecutar el servidor de desarrollo. El entrypoint maneja esto automáticamente en las construcciones con Docker.

Nota

src/content/docs/ se vacía durante la construcción de la imagen y está incluido en gitignore. Coloque contenido de prueba allí manualmente — no será confirmado en el repositorio.

Registro de imágenes

La imagen se publica en GitHub Container Registry:

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

Se publican dos etiquetas en cada construcción:

Etiqueta	Descripción
latest	Construcción más reciente desde main
<sha>	SHA completo del commit de Git para construcciones reproducibles

Consulte CI/CD y Gobernanza para el flujo de trabajo que construye y publica la imagen.