Guía Maestra de Despliegue en Cloudflare Pages y GitHub Privado#

Esta guía documenta la infraestructura, el mapa de herramientas MCP y el procedimiento operativo paso a paso para compilar y desplegar el portal de autoestudio en el dominio personalizado study.plynte.com, respaldado por un repositorio privado en github.com/franguh.

1. Mapa de Herramientas y Model Context Protocol (MCP)#

Una de las dudas fundamentales antes de iniciar la publicación es determinar qué herramientas y qué servidores de contexto (MCP) son estrictamente requeridos y cuáles son complementos opcionales.

1.1. Veredicto Inmediato: ¿Necesitas instalar algún MCP extra hoy?#

No. No requieres instalar ni configurar ningún servidor MCP adicional para compilar y desplegar el portal en este momento.

Tu entorno local en Windows ya cuenta de fábrica con las herramientas CLI completas y verificadas:

• Git (v2.54+): Control de versiones y exclusión atómica de archivos protegidos.
• GitHub CLI (gh): Autenticado con tu cuenta franguh para crear el repositorio remoto privado con un solo comando.
• Node.js (v22+): Ejecutor de JavaScript ultrarrápido para el generador de sitio estático.
• npx wrangler: Interfaz de línea de comandos oficial de Cloudflare para autenticación y despliegue directo a Cloudflare Pages sin intermediarios.

1.2. MCPs ya activos en tu agente#

Tu agente de inteligencia artificial ya dispone de 3 servidores MCP de alto valor que potencian el desarrollo:

1. context7: Consulta de documentación oficial y firmas de APIs en tiempo real (Rust, crates, Actix Web, SQLx, Web APIs).
2. codegraph: Indexación y navegación semántica del grafo de código fuente entre lecciones.
3. engram: Memoria episódica persistente que preserva contratos didácticos y notas de sesión.

1.3. MCPs opcionales para control autónomo remoto (Futuro)#

Si en el futuro deseas que el agente interactúe de forma autónoma con los paneles de control de Cloudflare y GitHub sin que tú tengas que introducir comandos en la terminal, puedes agregar opcionalmente:

• @cloudflare/mcp-server-cloudflare: Permite al agente crear proyectos en Pages, consultar analíticas y configurar registros DNS mediante la API de Cloudflare.
• @modelcontextprotocol/server-github o github-mcp-server: Permite al agente crear repositorios, gestionar ramas, pull requests e issues de GitHub vía token de acceso personal (PAT).

2. Comparativa de Alternativas de Lectura (iPad y Móvil)#

Para definir el mejor entorno de lectura del compendio (18 lecciones de Rust Full-Stack + 70 sesiones de algoritmos + 108 diagramas vectoriales interactivos), evaluamos tres alternativas:

Conclusión: La Opción 3 proporciona la experiencia más cómoda y profesional para el estudio diario continuo desde el iPad o el celular, manteniendo el código y apuntes bajo absoluta privacidad en GitHub.

3. Arquitectura del Sistema de Producción#

La arquitectura elegida desacopla de forma segura el entorno de desarrollo y autoría privada frente a la distribución pública optimizada para lectura en el Edge.

Componentes Clave de la Arquitectura#

1. Origen Local (E:\Learn): Código fuente, 88 lecciones/sesiones en Markdown y 108 diagramas SVG. El archivo .gitignore y .cfignore bloquean cualquier archivo PDF de referencia bajo docs/*.pdf.
2. Repositorio Privado (github.com/franguh/learn-rust-algorithms): Control de versiones privado accesible exclusivamente por el autor.
3. Pipeline de Construcción (Cloudflare Pages Build): - Comando de compilación: node scripts/build_study_site.mjs - Genera HTML semántico estático puro con buscador JSON indexado y copia de diagramas SVG hacia el directorio dist/.
4. Red Anycast Global de Cloudflare (study.plynte.com): - Registro CNAME apuntando study hacia <tu-proyecto>.pages.dev. - Distribución en más de 300 centros de datos globales con latencias inferiores a 25 ms. - Certificado TLS 1.3 administrado automáticamente con renovación sin coste.
5. Seguridad Endurecida (_headers): - Políticas estrictas de Content-Security-Policy (CSP), X-Frame-Options: DENY y prevención de ataques MIME.
6. Telemetría y Privacidad: - Cloudflare Web Analytics: Rendimiento y métricas sin cookies (cookieless). - Microsoft Clarity: Mapas de calor y sesiones reales con guarda de producción (study.plynte.com) para pulir la interfaz móvil.
7. Escudo Legal Integrado: - Declaración de contenido asistido por IA, Nominative Fair Use y enlace a LEGAL_Y_PRIVACIDAD.md.

4. Guía Operativa Paso a Paso#

Sigue estos pasos en orden para inicializar el repositorio, conectarlo a Cloudflare y configurar el dominio personalizado.

Paso 1: Verificar el Bloqueo de Archivos Sensibles y PDFs#

Antes de inicializar Git, confirma que .gitignore excluye permanentemente la carpeta docs/:

# Comprobar estado de exclusión en PowerShell
Test-Path "E:/Learn/.gitignore"
Get-Content "E:/Learn/.gitignore" | Select-String "docs"

Paso 2: Inicializar Git y Crear el Repositorio Privado en GitHub#

Abre PowerShell en E:\Learn y ejecuta:

cd E:\Learn

# 1. Inicializar repositorio local
git init -b main

# 2. Agregar archivos respetando .gitignore
git add .

# 3. Comprobar que ningún archivo PDF fue indexado
git status --short | Select-String "\.pdf"
# (El resultado DEBE estar completamente vacío)

# 4. Registrar el commit inicial
git commit -m "feat: initial commit with rust fullstack course, algorithms curriculum and diagrams"

# 5. Crear el repositorio en GitHub en modo PRIVADO y subir el código
gh repo create learn-rust-algorithms --private --source=. --remote=origin --push

Tu repositorio quedará alojado de forma privada y segura en: https://github.com/franguh/learn-rust-algorithms

Paso 3: Conectar el Repositorio a Cloudflare Pages#

Existen dos vías para el despliegue: mediante la interfaz web de Cloudflare (recomendada para CI/CD automático) o mediante la terminal con wrangler.

Opción A: Conexión Automática CI/CD desde el Panel de Cloudflare (Recomendada)#

1. Accede al Panel de Control de Cloudflare.
2. En el menú lateral izquierdo, haz clic en Workers & Pages > Overview > Create application > pestaña Pages.
3. Selecciona Connect to Git y autoriza tu cuenta de GitHub franguh.
4. Elige el repositorio privado learn-rust-algorithms.
5. En la sección Build settings, define: - Framework preset: None - Build command: node scripts/build_study_site.mjs - Build output directory: dist - Root directory: / (dejar en blanco o raíz) - Environment variables: * NODE_VERSION = 22
6. Haz clic en Save and Deploy. En ~25 segundos, Cloudflare compilará el sitio y te entregará una URL temporal https://<proyecto>.pages.dev.

Opción B: Despliegue Directo vía CLI con Wrangler#

Si prefieres desplegar directamente desde tu terminal local sin vincular el webhook:

cd E:\Learn

# 1. Compilar el portal en la máquina local
node scripts/build_study_site.mjs

# 2. Desplegar el directorio dist/ a Cloudflare Pages
npx wrangler pages deploy dist --project-name study-plynte

Paso 4: Configurar el Dominio Personalizado study.plynte.com#

Dado que tu dominio principal plynte.com ya se encuentra administrado en Cloudflare DNS:

1. En el panel del proyecto Cloudflare Pages recién creado, ve a la pestaña Custom domains.
2. Haz clic en Set up a custom domain.
3. Escribe el subdominio: study.plynte.com.
4. Haz clic en Continue.
5. Cloudflare detectará automáticamente la zona DNS de plynte.com y te solicitará confirmar la creación del registro: - Tipo: CNAME - Nombre: study - Destino: <nombre-del-proyecto>.pages.dev - Proxy status: Proxied (Nube naranja activada)
6. Haz clic en Activate domain.
7. En cuestión de 1 a 2 minutos, el certificado SSL/TLS universal se activará y el portal estará disponible globalmente en https://study.plynte.com.

Paso 5: Activar Analíticas Éticas y Microsoft Clarity#

1. Cloudflare Web Analytics (Cookieless)#

• En el panel de Cloudflare Pages, dirígete a la pestaña Analytics.
• Haz clic en Enable Web Analytics. Se habilitará de forma nativa sin requerir inyección de cookies de terceros.

2. Microsoft Clarity#

• Ingresa a https://clarity.microsoft.com/ con tu cuenta de Microsoft/GitHub.
• Crea un nuevo proyecto:
• Name: Study Plynte
• Website URL: https://study.plynte.com
• Copia tu Project ID alfanumérico (ejemplo: t9xxxxxx).
• El script de compilación scripts/build_study_site.mjs lee la variable de entorno CLARITY_PROJECT_ID o la constante configurada:
• En Cloudflare Pages: ve a Settings > Environment variables > añade CLARITY_PROJECT_ID con tu ID.
• O edita la constante en el script de build.
• La guarda de seguridad incorporada:

  if (window.location.hostname === 'study.plynte.com') {
    // Inicializar Clarity
  }

garantiza que Microsoft Clarity solo se ejecute en el dominio público de producción, manteniendo tus pruebas locales limpias.

5. Mantenimiento y Ciclo de Actualización#

A partir de este momento, cada vez que completes una lección, modifiques un código o crees un nuevo diagrama:

cd E:\Learn
git add .
git commit -m "docs: leccion 05 completada con soluciones verificadas"
git push origin main

Cloudflare Pages detectará automáticamente el push, ejecutará build_study_site.mjs y actualizará study.plynte.com en menos de medio minuto, manteniendo tu iPad y celular permanentemente sincronizados.