Nomenclatura de aplicaciones

🎯 Objetivo: Definir nombres consistentes para las aplicaciones.

Formato obligatorio

[cliente]-[app]-[ambiente]

Reglas

• Todo en minúsculas.
• Solo letras, números y guión medio (-).
• Sin espacios, tildes, ñ, guión bajo (_) ni caracteres especiales.
• cliente y app deben ser cortos y claros.
• ambiente debe ser uno de: prod, staging, dev, test.
• No repetir palabras entre cliente y app.

Ejemplos válidos

• trantor-form990-prod
• agrosuper-intranet-staging
• tallerdigital-crm-prod
• luksic-portal-dev

Ejemplos inválidos

• Trantor-Form990-Prod (mayúsculas)
• trantor_form990_prod (guión bajo)
• trantor-form 990-prod (espacio)
• trantor-form990-production (ambiente no estándar)
• trantor--form990-prod (doble guión)

Setup inicial de Cloudflare y Wrangler

Objetivo: preparar cuenta, autenticación y CLI para gestionar Pages, Workers y D1.

Requisitos previos

• Cuenta Cloudflare activa
• Node.js y npm instalados
• Dominio delegado en Cloudflare (si usarás dominio custom)

Instalar Wrangler

npm install -g wrangler
wrangler --version

Login a Cloudflare

wrangler login

Verificación

wrangler whoami

Crear proyecto Pages (frontend)

Objetivo: crear frontend desplegable en Cloudflare Pages.

Opción framework

npm create vite@latest <frontend_name>
cd <frontend_name>
npm install
npm run build

Opción HTML puro

Crear index.html, main.js y assets estáticos en el proyecto.

Verificación local

npm run dev

Crear base D1 y aplicar schema

Objetivo: provisionar SQLite serverless en Cloudflare D1.

Crear database

wrangler d1 create <db_name>

Guardar database_id retornado.

Crear schema

Crear archivo schema.sql con tablas e índices requeridos.

Aplicar schema

wrangler d1 execute <db_name> --file=./schema.sql

Verificación

wrangler d1 execute <db_name> --command "SELECT name FROM sqlite_master WHERE type='table';"

Crear Worker API y binding con D1

Objetivo: implementar backend API en Cloudflare Workers conectado a D1.

Crear proyecto Worker

npm create cloudflare@latest <worker_name>
cd <worker_name>

Configurar wrangler.toml

Agregar binding D1:

[[d1_databases]]
binding = "DB"
database_name = "<db_name>"
database_id = "<database_id>"

Implementar endpoints

Crear rutas API (GET/POST/etc.) con validación básica de input y acceso a env.DB.

Probar local

wrangler dev

Deploy Worker y dominio custom

Objetivo: publicar API en producción.

Configurar secrets

wrangler secret put <SECRET_NAME>

Deploy

wrangler deploy

Dominio custom (si aplica)

Configurar Custom Domains en Worker para exponer api.<dominio>.

Verificación

curl -I https://<api_domain>

Deploy frontend a Cloudflare Pages

Objetivo: publicar frontend y conectarlo al dominio final.

Deploy por Git (recomendado)

Conectar repo en Cloudflare Pages y definir:

• build command
• output directory
• variables de entorno

Deploy por CLI

wrangler pages deploy <output_dir> --project-name=<pages_project>

Dominio custom

Asociar dominio en Pages (www o root) y validar DNS.

Integrar Pages con Worker API

Objetivo: consumir API del Worker desde frontend sin errores de entorno ni routing.

Definir URL de API en frontend

Variables ejemplo:

VITE_API_URL=https://<api_domain>

Ajustar llamadas frontend

Usar URL configurable por entorno para fetch de datos.

Opción Pages Functions (simple)

Para casos sencillos, usar Pages Functions como capa intermedia.

Verificación

Abrir frontend en producción y confirmar requests exitosos a API.

Configurar R2 para archivos (opcional)

Objetivo: almacenar archivos/media fuera del runtime del Worker.

Crear bucket R2

Desde dashboard Cloudflare R2, crear bucket.

Configurar binding

Agregar binding R2 en wrangler.toml.

Verificación

Subir/leer archivo mediante endpoint del Worker y validar URL pública o privada según diseño.

Configurar analytics y monitoreo

Objetivo: observar tráfico, errores y rendimiento de frontend/API.

Web Analytics

Habilitar Cloudflare Web Analytics para Pages.

Workers Analytics

Revisar métricas de requests, errores y CPU time.

Logs en tiempo real

wrangler tail

Seguridad y validación final

Objetivo: validar seguridad mínima, conectividad y operación end-to-end.

Seguridad mínima

• WAF rules básicas para rutas sensibles
• Secrets en wrangler secret, no hardcodeados
• Validación de input en endpoints del Worker

Validación funcional

1. Probar frontend en dominio final.
2. Probar endpoints Worker (GET, POST) con datos reales.
3. Validar lecturas/escrituras en D1.
4. Validar SSL activo en frontend y API.

Comandos de chequeo

curl -I https://<frontend_domain>
curl -I https://<api_domain>
wrangler d1 execute <db_name> --command "SELECT COUNT(*) FROM <tabla>;"