Saltar a contenido

Publicar el hub en Cloudflare Pages

Requisitos

  • Cuenta de Cloudflare con acceso a la organización.
  • Repositorio VortexPlayDev/vortex-play-docs.
  • Python 3.12+ para builds locales.

Build local

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
mkdocs build --strict

El resultado queda en site/.

Opción A: integración directa con GitHub

Es la opción más simple y no requiere secretos en GitHub.

  1. En Cloudflare, ir a Workers & Pages → Create → Pages → Connect to Git.
  2. Seleccionar el repositorio VortexPlayDev/vortex-play-docs.
  3. Configurar:
  4. Production branch: main
  5. Build command: pip install -r requirements.txt && mkdocs build --strict
  6. Build output directory: site
  7. Guardar y desplegar.
  8. Configurar el dominio personalizado en Custom domains.

Cada push a main publica producción. Las ramas y PR pueden generar previews si se habilitan.

Opción B: GitHub Actions + Wrangler

El workflow .github/workflows/docs.yml ya está preparado.

  1. Crear el proyecto en Cloudflare:
npx wrangler pages project create vortex-play-docs --production-branch=main
  1. Crear un API token de Cloudflare con permiso Cloudflare Pages: Edit.
  2. Agregar los secretos en GitHub:
gh secret set CLOUDFLARE_API_TOKEN --repo VortexPlayDev/vortex-play-docs
gh secret set CLOUDFLARE_ACCOUNT_ID --repo VortexPlayDev/vortex-play-docs
  1. Hacer push a main o ejecutar el workflow manualmente.

El workflow instala dependencias, ejecuta mkdocs build --strict y despliega site/ con Wrangler usando wrangler.toml.

Proteger la documentación con Cloudflare Access

Si el hub debe ser interno:

  1. En Cloudflare Zero Trust, crear una aplicación de tipo Self-hosted.
  2. Asociar el dominio del hub.
  3. Definir una política de acceso, por ejemplo email OTP para el dominio de la empresa.
  4. Verificar que solo los usuarios autorizados puedan abrir el sitio.

Verificación

  • Abrir la URL de producción y comprobar navegación y búsqueda.
  • Revisar que los enlaces internos funcionen.
  • Confirmar que el workflow termina en verde.
  • Verificar que Access bloquea el acceso sin autenticación, si está habilitado.

Rollback

Cloudflare Pages conserva los despliegues anteriores. Si una publicación falla:

  1. Ir al proyecto en Cloudflare Pages.
  2. Abrir Deployments.
  3. Seleccionar el despliegue anterior estable.
  4. Promoverlo a producción o hacer rollback desde la interfaz.

Notas

  • No guardar tokens de Cloudflare en el repositorio.
  • El token debe limitarse al proyecto y tener el mínimo permiso necesario.
  • Si se cambia el nombre del proyecto, actualizar wrangler.toml y el workflow.