Runbook W-2: Despliegue Manual de la Wiki en Cloudflare Pages + Zero Trust

Iniciativa: Wiki + Guía de Usuario y Chatbot (Fase W-2)
Fecha: 2026-09-28
Estado: Listo para Ejecución por el Operador
Propósito: Guía paso a paso, precisa y libre de secretos para el operador del sistema. Instruye la conexión del repositorio privado a Cloudflare Pages, el comando de compilación de wiki/, la asignación del subdominio institucional y la protección perimetral con Cloudflare Zero Trust (One-Time PIN).

---

🎯 Resumen Ejecutivo y Arquitectura del Despliegue

La Wiki Técnica de ITECEL ADM está desacoplada de la aplicación web principal. Reside en la carpeta wiki/ del repositorio y compila de forma estática directamente los archivos de docs/ como fuente única de verdad, sin duplicación de contenidos.

---

📋 Superficies de Despliegue Oficiales (Regla R1 / ADR-011)

A partir de esta fase, el ecosistema ITECEL ADM opera sobre tres superficies de despliegue:

Superficie	Plataforma	Disparador	Componentes Desplegados	Dominio
1. App Web	Vercel	Automático (git push main)	Frontend React (src/, public/)	adm.itecelgs.com
2. Backend	Supabase	Manual (Dashboard)	Edge Functions (supabase/functions/) y Esquema SQL	Proyecto Supabase Producción
3. Wiki Técnica	Cloudflare Pages	Automático (git push main)	Sitio VitePress (wiki/ leyendo docs/)	wiki-adm.itecelgs.com (Protegido por Zero Trust)

---

🛠️ Procedimiento Paso a Paso para el Operador

Paso 1: Conexión de GitHub y Cloudflare

1. Iniciar sesión en el portal de Cloudflare Dashboard.
2. En el menú de navegación lateral, ir a Compute (Workers & Pages) → Pages.
3. Hacer clic en Create application (o Connect to Git).
4. Seleccionar la pestaña Pages y hacer clic en Connect to Git.
5. Si no está conectado GitHub:
   • Seleccionar Connect GitHub.
   • Conceder permisos a Cloudflare para acceder al repositorio privado zjuanf5-ai/ITECEL-ADM.
6. Seleccionar el repositorio zjuanf5-ai/ITECEL-ADM y hacer clic en Begin setup.

---

Paso 2: Configuración del Proyecto y Build Settings

Completar el formulario de configuración con los siguientes valores exactos:

Campo	Valor Configurado	Justificación Técnica
Project name	itecel-adm-wiki	Nombre del proyecto en Cloudflare (genera itecel-adm-wiki.pages.dev).
Production branch	main	Cada push a la rama principal actualizará la documentación.
Framework preset	None (o VitePress)	Control manual y explícito de comandos de compilación.
Root directory	/ (raíz del repo)	Permite ejecutar scripts desde la raíz apuntando a wiki/.
Build command	cd wiki && npm install && npm run docs:build	Instala dependencias aisladas de la wiki y genera el bundle estático.
Build output directory	wiki/.vitepress/dist	Carpeta donde VitePress deposita los archivos compilados listos para servir.

Variables de Entorno de Build (Environment variables):

Dentro de la sección Environment variables (advanced), agregar:

• Variable: NODE_VERSION
• Valor: 20 (o 22)

Hacer clic en Save and Deploy. Cloudflare ejecutará el primer build de prueba.

---

Paso 3: Asignación de Subdominio en DNS

Subdominio Canónico Propuesto: wiki-adm.itecelgs.com
Aislamiento: Este registro es un registro CNAME independiente. NO toca, no altera y no interfiere en lo absoluto con adm.itecelgs.com ni con los registros MX/SPF de correo de itecelgs.com.

1. En el proyecto recién creado en Cloudflare Pages, ir a la pestaña Custom domains.
2. Hacer clic en Set up a custom domain.
3. Ingresar: wiki-adm.itecelgs.com.
4. Si la zona DNS de itecelgs.com está administrada en Cloudflare:
   • Cloudflare configurará automáticamente el registro CNAME con proxy activado (nube naranja).
5. Si la zona DNS se administra externamente:
   • Crear un registro CNAME en el proveedor DNS:
     • Host / Nombre: wiki
     • Destino: itecel-adm-wiki.pages.dev
     • Proxy / TTL: Activado o Automático.
6. Esperar a que el certificado SSL universal se active (típicamente 1-3 minutos).

---

Paso 4: Protección Perimetral con Cloudflare Zero Trust (Access)

⚠️ REQUISITO ESTRICTO: La documentación técnica contiene diagramas de arquitectura, catálogo de tablas, políticas RLS y decisiones internas del sistema. Queda terminantemente prohibido dejar el sitio público.

1. En Cloudflare Dashboard, hacer clic en el menú lateral en Zero Trust.
2. Ir a Access → Applications.
3. Hacer clic en Add an application y seleccionar Self-hosted.
4. Configuración de la Aplicación:
   • Application name: ITECEL ADM - Wiki Técnica
   • Session Duration: 24 hours (o 7 days a criterio del operador).
   • Application domain:
     • Subdomain: wiki
     • Domain: itecelgs.com
     • Path: (dejar vacío para proteger todo el sitio)
5. Configuración del Proveedor de Identidad:
   • En Identity providers, asegurarse de tener activo One-Time PIN (OTP) (habilitado por defecto en Cloudflare Access, envía un código numérico temporal al correo).
6. Creación de la Política de Acceso (Policy):
   • Policy name: Equipo Autorizado ITECEL
   • Action: Allow
   • Configure rules (Include):
     • Selector: Emails
     • Value: Ingresar las direcciones de correo del operador, directivos y equipo técnico con autorización de lectura (ej. juanfelipe@itecelgs.com, etc.).
7. Guardar la aplicación presionando Save application.

🧪 Prueba de Validación de Bloqueo (Navegador Limpio):

1. Abrir una ventana de navegación privada / incógnito.
2. Navegar a https://wiki-adm.itecelgs.com.
3. Resultado esperado:
   • Redirección inmediata a https://<equipo>.cloudflareaccess.com/cdn-cgi/access/login/....
   • Ningún recurso estático (.html, .js, .css) debe responder con código 200 sin haber validado el PIN enviado al correo.
   • Introducir el correo autorizado → recibir el PIN de 6 dígitos → ingresar el PIN → Acceso concedido a la Wiki.

---

Paso 5: Checklist Post-Despliegue

Completar la siguiente lista de verificación una vez publicado el sitio:

• [ ] Acceso Restringido Validado: Sesión anónima es bloqueada al 100% por Cloudflare Zero Trust.
• [ ] Portada Activa: https://wiki-adm.itecelgs.com carga el Índice Maestro (INDEX.md) con formato, títulos y enlaces.
• [ ] Diagramas Mermaid en Arquitectura: Navegar a /ARQUITECTURA y comprobar que el diagrama general y la cadena de identidad se dibujan como vectores SVG limpios y legibles.
• [ ] Diagrama ERD en Datos: Navegar a /DATOS y comprobar que el diagrama Entidad-Relación de tablas condominios/viviendas renderiza como SVG.
• [ ] Búsqueda Local Operativa: Presionar Ctrl + K (o hacer clic en "Buscar en la Wiki"), buscar términos clave (ej. ADR-001, presupuesto, cuotas) y verificar que los resultados aparecen instantáneamente.
• [ ] Prueba de Redeploy Continuo: Realizar un commit menor en docs/ y push a main; verificar en Cloudflare Pages que el pipeline inicia y finaliza en verde en menos de 5 minutos sin intervención manual.

---

🛑 Plan de Contingencia / Rollback

Si el despliegue falla en Cloudflare Pages:

1. Error en Build: Revisar en Cloudflare Pages → Deployments → View build log. Verificar que NODE_VERSION esté fijada en 20 y que el comando sea cd wiki && npm install && npm run docs:build.
2. Error en Zero Trust: Si un miembro del equipo no puede acceder, verificar en Zero Trust → Access → Applications que su correo coincida exactamente (sin espacios ni mayúsculas inconsistentes).
3. Rollback Rápido: En Cloudflare Pages → Deployments, hacer clic en los tres puntos de un despliegue previo exitoso y seleccionar Rollback to this deployment.