Documentación del Sistema

Appearance

Infraestructura y Deployment ​

Opciones de Infraestructura ​

Opción 1: VPS Compartido (Recomendado para MVP) ​

Stack requerido:

  • Ubuntu 22.04 LTS
  • Apache con mod_proxy (o Nginx)
  • PHP 8.2-FPM
  • PostgreSQL 14+
  • Node.js 18+ (solo para build, NO en runtime)
  • Redis (opcional - cache y rate limiting)

Ventajas:

  • Costo bajo
  • Control total
  • Simple de configurar

Desventajas:

  • Escalabilidad limitada
  • Requiere mantenimiento manual

Opción 2: Contenedores (Docker) ​

Servicios:

  • Backend: PHP-FPM + Slim Framework
  • Frontend: Nginx sirviendo archivos estáticos
  • Postgres: Base de datos multi-tenant
  • Redis: Cache y rate limiting

Ventajas:

  • Aislamiento de servicios
  • Fácil de replicar
  • Escalable horizontalmente

Configuración DNS ​

Wildcard DNS ​

Permite múltiples subdominios automáticamente:

*.bautista.com → A record → 123.45.67.89

Habilita:

  • ctacte.bautista.com
  • empresaA.bautista.com
  • clubXYZ.bautista.com

Dominios Personalizados ​

Para clientes que quieren su propio dominio:

ctacte.empresaA.com → CNAME → portal.bautista.com
portal.clubXYZ.com  → CNAME → portal.bautista.com

Proceso:

  1. Cliente configura CNAME en su DNS
  2. Se agrega dominio a tenant_domains
  3. Se genera certificado SSL
  4. Se agrega ServerAlias en configuración de servidor

SSL/TLS ​

Wildcard Certificate ​

Un solo certificado para todos los subdominios:

  • *.bautista.com
  • bautista.com

Ventajas:

  • Un solo certificado para mantener
  • Nuevos subdominios funcionan inmediatamente

Herramienta: Let's Encrypt con certbot

Certificados Individuales ​

Generar certificado por cada dominio personalizado.

Cuando usar:

  • Dominios personalizados de clientes (ej: ctacte.empresaA.com)

Auto-renewal: Configurar renovación automática cada 60 días.

Servidor Web ​

Configuración Principal ​

Frontend (Vite build estático):

  • Servir archivos desde /dist/
  • SPA routing: todas las rutas → index.html
  • Cache busting para assets con hash
  • Headers de seguridad (HSTS, CSP)

Backend (API proxy):

  • Proxy /api/* → Backend PHP en puerto 8000
  • Agregar header X-Client-Domain con el dominio del request
  • Timeout de 60 segundos

HTTP → HTTPS:

  • Redirect permanente de puerto 80 a 443

Build y Deploy ​

Backend ​

Pasos:

  1. Instalar dependencias PHP (composer install)
  2. Ejecutar migraciones de base de datos
  3. Configurar permisos de archivos
  4. Reiniciar PHP-FPM

Resultado: API REST disponible en /api/*

Frontend ​

Pasos:

  1. Instalar dependencias Node.js (npm ci)
  2. Build con Vite (npm run build)
  3. Copiar archivos de dist/ al servidor
  4. Reload servidor web

Resultado:

  • Build estático en dist/
  • NO requiere Node.js en producción
  • Servidor web sirve archivos directamente

Deployment con Cero Downtime ​

Estrategia:

  1. Build en directorio temporal con timestamp
  2. Atomic symlink swap
  3. Reload servidor (sin restart completo)

Beneficio: Los usuarios no ven downtime durante deploy.

Configurar Nuevo Tenant ​

Pasos ​

  1. Alta en base de datos:

    • Insertar en tenant_domains con:
      • domain
      • database
      • branding_config (colores, logo, nombre)

  2. Configurar DNS:

    • CNAME del dominio del tenant → servidor principal

  3. Generar SSL:

    • Certificado para el dominio del tenant

  4. Configurar servidor web:

    • Agregar dominio como ServerAlias

  5. Reload servidor:

    • Aplicar cambios sin downtime

Script CLI ​

Automatizar el proceso con script que:

  • Inserta en tenant_domains
  • Guía configuración DNS
  • Genera certificado SSL
  • Actualiza configuración del servidor

Monitoreo ​

Logs a Monitorear ​

  • Apache/Nginx: Access y error logs
  • PHP-FPM: Error logs
  • PostgreSQL: Query logs y error logs
  • Aplicación: Logs estructurados (JSON)

Health Checks ​

Backend API:

GET /health
Response: { "status": "ok", "database": "connected" }

Frontend:

GET /
Response: 200 OK

Database:

  • Verificar conexión
  • Count de tenant_domains activos

Métricas Importantes ​

  • Tiempo de respuesta de API
  • Tasa de error (5xx)
  • Uso de CPU/RAM
  • Conexiones a base de datos
  • Rate de requests por tenant

Backup ​

Base de Datos ​

Diario:

  • Backup completo de cada tenant
  • Retention: 7 días

Semanal:

  • Backup de todas las bases de datos
  • Retention: 4 semanas

Mensual:

  • Backup completo archivado
  • Retention: 12 meses

Código ​

  • Repositorio Git como backup principal
  • Branches protegidos (main, develop)

Assets ​

  • Logo y archivos de branding
  • Backup semanal

Seguridad ​

Headers de Seguridad ​

  • Strict-Transport-Security: Forzar HTTPS
  • Content-Security-Policy: Prevenir XSS
  • X-Frame-Options: Prevenir clickjacking
  • X-Content-Type-Options: Prevenir MIME sniffing

Firewall ​

  • Puertos abiertos: 80, 443 (HTTP/HTTPS)
  • Puertos cerrados: 5432 (PostgreSQL), 6379 (Redis)
  • Solo backend puede acceder a DB/Redis

Rate Limiting ​

  • Max 100 requests/minuto por IP
  • Max 5 intentos de login/minuto
  • Bloqueo temporal después de 3 fallos

Escalabilidad ​

Vertical (Más recursos) ​

  • Aumentar CPU/RAM del servidor
  • Optimizar queries de base de datos
  • Agregar Redis para cache

Horizontal (Más servidores) ​

Frontend:

  • CDN para assets estáticos
  • Múltiples servidores con load balancer

Backend:

  • Múltiples instancias PHP-FPM
  • Load balancer (HAProxy, Nginx)
  • Session sticky o JWT stateless

Database:

  • Read replicas para consultas
  • Connection pooling (PgBouncer)

Próximos Pasos ​

  1. Ver configuración avanzada de dominios en domains.md
  2. Configurar monitoreo con herramientas como Prometheus/Grafana
  3. Implementar CI/CD para deployment automático