Pla de Desplegament de Documentació

⚠️ ESTAT: PENDENT D'IMPLEMENTAR

Aquest document descriu el pla proposat per desplegar la documentació Docusaurus a Cloudflare Pages amb autenticació. Queda pendent d'implementar en una fase futura.

Resum Executiu

Objectiu: Publicar la documentació del projecte Line Dance Platform de manera segura, accessible només per usuaris autoritzats.

Solució Proposada: Cloudflare Pages + Cloudflare Access

Cost: Gratuït (dins dels límits del pla free)

Arquitectura Proposada

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   GitHub Repo   │────▶│ Cloudflare Pages │────▶│ Cloudflare      │
│ line-dance-docs │     │   (Build & Host) │     │ Access (Auth)   │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                                                          │
                                                          ▼
                                                 ┌─────────────────┐
                                                 │  Usuaris        │
                                                 │  Autoritzats    │
                                                 └─────────────────┘

Passos d'Implementació

Fase 1: Preparació del Repositori

1. Crear repositori separat per documentació

   • Nom: Susisco/line-dance-docs
   • Contingut: només la carpeta docs-web/
   • Motiu: aïllar la documentació del codi font

2. Configurar GitHub Actions per sincronització (opcional)

   # .github/workflows/sync-docs.yml
   name: Sync Docs
   on:
     push:
       paths:
         - 'docs-web/**'
   jobs:
     sync:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - name: Push to docs repo
           # Configurar push al repo de docs

Fase 2: Configuració Cloudflare Pages

1. Crear compte Cloudflare (si no existeix)

   • Registrar-se a dash.cloudflare.com

2. Connectar repositori

   • Cloudflare Dashboard → Pages → Create Project
   • Connectar GitHub → Seleccionar line-dance-docs

3. Configurar build

   Build command: npm run build
   Build output directory: build
   Root directory: / (o docs-web/ si és subrepo)
   Node.js version: 20

4. Variables d'entorn (si cal)

   NODE_VERSION=20

Fase 3: Configuració Cloudflare Access

1. Crear Access Application

   • Zero Trust → Access → Applications → Add Application
   • Tipus: Self-hosted
   • Nom: "Line Dance Docs"
   • Subdomini: docs.line-dance-platform.pages.dev (o domini propi)

2. Configurar política d'accés

   • Policy name: "Team Access"
   • Decision: Allow
   • Include rules:
     • Login Methods: GitHub (comptes específics)
     • O bé: Emails ending in @domini-empresa.com

3. Opcions d'autenticació

   • GitHub OAuth (recomanat per desenvolupadors)
   • Google Workspace (si teniu domini corporatiu)
   • One-time PIN via email

Fase 4: Domini Personalitzat (Opcional)

1. Afegir domini a Cloudflare

   • Exemple: docs.linedanceplatform.com

2. Configurar DNS

   CNAME docs -> line-dance-docs.pages.dev

Consideracions de Seguretat

Avantatges de Repositori Separat

Aspecte	Repo Unit	Repo Separat
Exposició codi	⚠️ Tot visible	✅ Només docs
Secrets	⚠️ Risc potencial	✅ Aïllats
Velocitat build	🐢 Més lent	🚀 Més ràpid
Manteniment	✅ Un sol lloc	⚠️ Sincronització

Control d'Accés Granular

Per seccions amb diferent nivell d'accés:

Opció A: Múltiples instàncies

• docs-public.pages.dev → Sense auth
• docs-internal.pages.dev → Amb Access

Opció B: Path-based policies (Access Enterprise)

• /public/* → Accés lliure
• /internal/* → Requereix auth

Estimació de Temps

Tasca	Temps Estimat
Crear repo separat	15 min
Configurar Cloudflare Pages	20 min
Configurar Access	30 min
Testing i ajustos	30 min
Total	~1.5 hores

Checklist d'Implementació

• Crear repositori Susisco/line-dance-docs
• Copiar contingut docs-web/ al nou repo
• Registrar compte Cloudflare (si cal)
• Crear projecte a Cloudflare Pages
• Verificar build correcte
• Configurar Cloudflare Access
• Afegir política d'autenticació
• Provar accés amb usuari autoritzat
• Provar denegació amb usuari no autoritzat
• Documentar URLs finals
• (Opcional) Configurar domini personalitzat

Recursos

• Cloudflare Pages Documentation
• Cloudflare Access Documentation
• Docusaurus Deployment Guide

Historial

Data	Acció	Autor
2026-02-03	Document creat com a proposta	-
-	Pendent d'implementació	-

---

Última actualització: 2026-02-03