Saltar al contenido principal

Despliegue con Docker

Esta guía resume los pasos recomendados para llevar Floutic a un entorno productivo usando Docker Compose.

Pre-requisitos​

  • Infraestructura: host Linux (Ubuntu 22.04 LTS o similar) con Docker 24+ y Docker Compose v2
  • Recursos: Recomendado: 4 vCPU, 8 GB RAM y 50 GB de disco SSD para entornos pequeños
  • Dependencias del sistema: instalar curl, git, docker, docker compose. Añadir el usuario desplegador al grupo docker
  • Networking: abrir puertos 80/443 (reverse proxy) y restringir 5432 (PostgreSQL) y 6379 (Redis) a la red interna/VPC
  • Dominio: DNS apuntando a los hosts públicos (FRONTEND_HOST, BACKEND_HOST, DOCS_HOST)
  • Certificados TLS: manejar certificados vía Traefik/Caddy/NGINX (Let's Encrypt)
  • Almacenamiento persistente: provisionar volúmenes para PostgreSQL (docker-volumes/postgres/data) y Redis (docker-volumes/redis/data)

Variables de Entorno​

  1. Revisa el .env raíz existente y sepáralo:
    • Copia backend/.env.production.example como backend/.env (o similar) y rellena con valores reales
    • Copia frontend/.env.production.example para el proceso de build del frontend
  2. Consulta Variables de Entorno para detalles de cada variable
  3. Mantén secretos (Stripe, JWT, SMTP) fuera del repositorio; usa gestores como AWS SSM, Vault o configuraciones cifradas

Preparar Imágenes​

El repositorio incluye Dockerfiles:

  • backend/Dockerfile
  • frontend/Dockerfile y frontend/Dockerfile.dev
  • docs-site/Dockerfile

Para producción, se recomienda construir imágenes específicas:

docker compose -f docker-compose.yml build --no-cache backend frontend docs

Genera tags y súbelas a tu registry si no desplegarás desde el repositorio directamente.

Migraciones de Base de Datos​

  1. Copia los ficheros backend y alembic al servidor o usa el contenedor backend para aplicar migraciones
  2. Ejecuta (con variables cargadas):
docker compose run --rm backend alembic upgrade head
  1. Verifica que la tabla de versiones (alembic_version) está actualizada

Configuración adicional de PostgreSQL y Redis​

  • Revisa los volúmenes configurados en docker-compose.yml y asegúrate de que apuntan a discos persistentes con backups periódicos
  • Para PostgreSQL gestionado (RDS, Cloud SQL, etc.) actualiza DATABASE_URL y habilita SSL si es obligatorio
  • Configura parámetros de mantenimiento: max_connections, shared_buffers y timezone
  • Para Redis, define políticas de persistencia (appendonly yes si se requiere) y límites de memoria/failover

Despliegue con Docker Compose​

  1. Asegúrate de que las redes externas referenciadas en docker-compose.yml (web) existen o ajusta el archivo a tus necesidades
  2. Exporta las variables de entorno adecuadas (o usa un .env en el directorio raíz con valores de producción)
  3. Levanta servicios:
docker compose up -d postgres redis
# esperar a que estén healthy
docker compose up -d backend frontend docs
  1. Comprueba logs y healthchecks:
docker compose logs -f backend
curl https://api.tu-dominio.com/health

Reverse Proxy / TLS​

El docker-compose.yml incluye etiquetas para Traefik y Caddy. Si empleas esos proxies:

  • Configura Traefik/Caddy en la red web para solicitar certificados Let's Encrypt
  • Define variables BACKEND_HOST, FRONTEND_HOST y DOCS_HOST con tus dominios
  • Asegúrate de redirigir tráfico HTTP → HTTPS

Si usas Nginx u otro proxy externo, expón backend:8000, frontend:3000 y docs:3000 internamente y configura el proxy manualmente.

Monitorización y Logs​

  • Exponer PROMETHEUS_PORT si quieres scrapear métricas propias y conectar un servidor Prometheus/Grafana
  • Configura alertas sobre el healthcheck (/health) y tiempos de respuesta (5xx repetidos, timeouts)
  • Centraliza logs con docker compose logs o herramientas como Loki/ELK; establece rotación (logrotate) para evitar llenar disco
  • Integra un servicio de error reporting (Sentry, Rollbar) si se requiere trazabilidad de excepciones
  • Revisa los estados de Stripe y GHL webhooks después del despliegue; corrige inmediatamente los intentos fallidos

Tareas Post Despliegue​

  1. Ejecuta smoke tests: login, creación de proyecto, flujo de pago de prueba (con Stripe Test)
  2. Valida recepción de emails y webhooks en Stripe y GoHighLevel
  3. Revisa la consola de Stripe y GHL para confirmar registros y datos sincronizados
  4. Completa la Checklist de Deployment

Troubleshooting​

  • Backend 5xx: usa docker compose logs backend y revisa la BD. Comprueba JWT_SECRET, conexión a PostgreSQL/Redis y migraciones
  • Stripe: confirma que las claves live/test coinciden con el entorno, que el webhook apunta a /api/payments/webhooks/stripe y que las firmas son válidas
  • GoHighLevel: revisar ghl_sync_log en busca de errores. Si hay fallos reiterados, valida API Key y permisos en GHL
  • CORS / URLs: asegúrate de que FRONTEND_URL, CORS_ORIGINS y VITE_API_BASE_URL coinciden con los dominios desplegados
  • Recursos: monitoriza uso de disco/RAM/CPU (docker stats, df -h). Ajusta ulimits o tamaños de volumen si se agotan
  • SSL/TLS: si el navegador marca sitio inseguro, revisa certificados emitidos por Traefik/Caddy o renueva manualmente con Let's Encrypt

Backups y Restauración​

PostgreSQL​

Programa pg_dump (o snapshots gestionados) antes de cada despliegue:

PGPASSWORD=$POSTGRES_PASSWORD pg_dump -h $POSTGRES_HOST -U $POSTGRES_USER $POSTGRES_DB > backup.sql

Para restaurar: psql -h ... -U ... -d ... < backup.sql

Redis​

Si usas Redis para sesiones, habilita SAVE/AOF o exporta la RDB antes de operaciones de riesgo.

Almacenamiento​

Copia volúmenes (docker-volumes/postgres, docker-volumes/redis) a un bucket seguro si el entorno es autogestionado.

Rollback Rápido​

  • Conserva la imagen anterior del backend/frontend (taggeada en el registry) para revertir rápidamente (docker compose pull con tag previo)
  • Si la migración introdujo errores, usa alembic downgrade -1 (o al revision id anterior). Documenta siempre los downgrades seguros
  • Reaplica backups (pg_restore) si la BD quedó inconsistente
  • Comunica a soporte/usuarios si hay impacto y deja anotado en el checklist cualquier incidencia

Más Información​