Despliegue de Guide Library¶

Esta guia explica como publicar la biblioteca como web-app estatica en library.curiositasmundus.com.

Para operacion diaria, mantenimiento y decisiones de contenido, leer tambien OPERACIONES_GUIDE_LIBRARY.md.

Que queda preparado en el repositorio¶

mkdocs.yml: configuracion de la web-app.
requirements.txt: dependencias de construccion.
scripts/build_guide_library.py: prepara los Markdown para la web sin modificar los documentos originales.
webapp/: icono, estilos, manifiesto PWA y service worker basico.

La fuente de verdad sigue siendo la biblioteca Markdown original. La carpeta .mkdocs/ y la carpeta site/ son generadas y no deben editarse a mano.

Probar en local¶

python scripts/build_guide_library.py
mkdocs serve

En esta maquina, si python abre el Python antiguo de Inkscape, usar:

py -3.14 scripts/build_guide_library.py
py -3.14 -m mkdocs serve

Configurar Cloudflare Pages¶

Entrar en Cloudflare.
Ir a Workers & Pages.
Elegir Create application.
Elegir Pages.
Elegir Connect to Git.
Autorizar GitHub y seleccionar el repositorio tours.
Configurar:
Project name: guides-library.
Production branch: main.
Framework preset: ninguno / no framework.
Build command:

pip install -r requirements.txt && python scripts/build_guide_library.py && mkdocs build

Build output directory:

site

Root directory: dejar vacio si el repositorio completo es la raiz.
Guardar y desplegar.

Conectar `library.curiositasmundus.com`¶

Despues del primer despliegue:

Entrar en el proyecto de Cloudflare Pages.
Abrir Custom domains.
Anadir library.curiositasmundus.com.
Si el DNS del dominio esta en Cloudflare, Cloudflare puede crear el registro automaticamente.
Si el DNS no esta gestionado en Cloudflare, crear un CNAME:

Type: CNAME
Name: library
Target: <nombre-del-proyecto>.pages.dev

Importante: el subdominio creado en cPanel apunta a una carpeta del hosting tradicional. Para usar Cloudflare Pages, el DNS de library.curiositasmundus.com debe apuntar al proyecto de Pages, no a la carpeta de cPanel.

Cambiar o comprobar la rama de produccion¶

Cloudflare Pages debe quedar apuntando a:

main

Si se usa temporalmente una rama codex/... para probar, volver despues a main cuando el PR este fusionado.

Ruta orientativa:

Cloudflare Pages.
Proyecto guides-library.
Settings.
Builds and deployments.
Production branch.
Seleccionar main.
Guardar y lanzar nuevo deploy si hace falta.

Proteger con acceso por email¶

En Cloudflare Zero Trust:

Ir a Access.
Crear una aplicacion Self-hosted.
Dominio de la aplicacion: library.curiositasmundus.com.
Metodo de login sencillo: One-time PIN por email.
Politica inicial:
Allow.
Include: emails terminados en curiositasmundus.com.

Mas adelante, si la app se convierte en producto de pago, esta capa se puede cambiar por una lista de emails concretos, grupos, o un sistema de pagos y usuarios.

Que hacer si falla un despliegue¶

Falta `requirements.txt`¶

Cloudflare esta construyendo una rama antigua.

Accion:

Comprobar que Production branch es main.
Comprobar que main contiene requirements.txt, mkdocs.yml y scripts/build_guide_library.py.
Lanzar Retry deployment.

El dominio abre cPanel o una pagina vacia¶

El DNS del subdominio no apunta a Cloudflare Pages.

Accion:

Revisar Custom domains en Pages.
Revisar el CNAME library.
Debe apuntar a guides-library.pages.dev si Cloudflare no lo gestiona automaticamente.

El build funciona pero hay avisos¶

Si son avisos de anclas no encontradas, la web se genera, pero algunos enlaces a secciones pueden saltar mal. Corregir los indices rapidos cuando se trabaje ese tour.

Notas de contenido pendientes¶

La app construye correctamente, pero el build avisa de contenido pendiente:

Algunos indices rapidos apuntan a anclas antiguas que no coinciden exactamente con los encabezados actuales.

Estos avisos no bloquean el despliegue inicial, pero conviene corregirlos para que la navegacion durante tours sea perfecta.