Ejemplo: despliegue con Docker Compose

Esta página ilustra, a modo de ejemplo, un despliegue on-premise de FoxPlan en un servidor único con Docker Compose y Traefik como reverse proxy (terminación TLS y certificados Let's Encrypt automáticos).

nota

Los archivos exactos (docker-compose.yml, scripts, configuración de Traefik) se entregan con el paquete de despliegue on-premise. Los extractos siguientes se ofrecen para comprender el funcionamiento de conjunto.

Arquitectura

                 Internet (DNS: DOMAIN → este servidor)
                          │  80 / 443
                          ▼
                      ┌────────┐   TLS Let's Encrypt (ACME)
                      │ Traefik│   redirección 80 → 443
                      └───┬────┘
        ┌─────────────────┼───────────────────────────┐
        ▼                 ▼                ▼            ▼
   / (app:5000)   /docs (docs:8080)  /_maintenance   (conmutación)
   product-server     docs           maintenance-toggle  maintenance
        │
        ├──► mongo (red interna)
        └──► redis (red interna)

Se proporcionan dos variantes:

• docker-compose.yml — una instancia de la aplicación;
• docker-compose-scale.yml — varias instancias, cuya carga reparte automáticamente Traefik.

Requisitos previos

• Un servidor Linux con Docker y Docker Compose v2;
• Un nombre de dominio cuyo registro DNS apunte al servidor;
• Los puertos 80 y 443 abiertos desde Internet (obligatorio para el desafío ACME);
• Acceso al registro de imágenes de FoxPlan y su licencia.

Configuración

1. Preparación inicial

Un script prepara el entorno (archivo .env, almacenamiento de los certificados, credenciales del panel de mantenimiento):

MAINT_USER=foxops MAINT_PASS='una_contraseña_robusta' ./setup-compose.sh

2. Variables de infraestructura (.env)

Variable	Descripción
DOMAIN	Dominio público servido (p. ej. app.mi-empresa.com)
ACME_EMAIL	Email de contacto de Let's Encrypt
APP_IMAGE	Imagen de la aplicación a desplegar (registro/tag)

3. Secretos de la aplicación

Se crean tres archivos de secretos a partir de sus plantillas .example, y después se rellenan:

cp .env_application.example .env_application   # variables de la app (BD, OAuth, S3, JWT…)
cp .env_mongo.example       .env_mongo         # credenciales de MongoDB
cp .env_redis.example       .env_redis         # contraseña de Redis

Coherencias que respetar:

• URL_MONGO utiliza el usuario/contraseña de .env_mongo, con el host mongo;
• SPRING_REDIS_PASSWORD es idéntica a REDIS_PASSWORD;
• BASE_URL corresponde a https:// + DOMAIN.

Puesta en marcha

# Variante simple (1 instancia)
docker compose up -d --build

# Variante escalada (varias instancias)
docker compose -f docker-compose-scale.yml up -d --build
docker compose -f docker-compose-scale.yml up -d --scale product-server=4

En el primer arranque, Traefik obtiene automáticamente el certificado de Let's Encrypt. Verificación:

docker compose logs -f traefik     # seguir la obtención del certificado
curl -I https://SU_DOMINIO/        # debe responder 200 con un certificado válido
curl -I https://SU_DOMINIO/docs/

Modo mantenimiento

El sitio puede conmutar a una página de mantenimiento (la documentación /docs sigue accesible).

• Desde el navegador: acceda a https://SU_DOMINIO/_maintenance (protegido por contraseña), y después Activar / Restablecer.
• Desde la línea de comandos:

./compose-maintenance.sh on        # activa el mantenimiento
./compose-maintenance.sh off       # restablece la aplicación
./compose-maintenance.sh status    # estado actual

La conmutación es instantánea y no reinicia ningún contenedor (recarga en caliente de Traefik).

Certificados TLS (Let's Encrypt)

• Obtenidos y renovados automáticamente por Traefik (desafío HTTP-01);
• No se requiere ninguna acción manual para la renovación.

Si el certificado no se emite, verifique en este orden:

1. El dominio resuelve correctamente hacia el servidor (dig +short SU_DOMINIO);
2. Los puertos 80 y 443 están abiertos desde Internet;
3. Los logs: docker compose logs traefik | grep -i acme.

Explotación habitual

docker compose ps                              # estado de los servicios
docker compose logs -f product-server          # logs de la aplicación
docker compose pull product-server && docker compose up -d   # actualización
docker compose down                            # parada (conserva los datos)

Los datos de MongoDB y Redis se conservan en volúmenes con nombre, que sobreviven a las paradas/reinicios.

Solución de problemas

Síntoma	Pista
404 en /	DOMAIN incorrecto, o aplicación no iniciada (ver logs)
502 / 503	La aplicación aún no escucha, o error en el arranque
Certificado no válido	DNS, puertos 80/443, logs ACME (ver más arriba)
/_maintenance en bucle de autenticación	Regenerar las credenciales con setup-compose.sh
Error de autenticación de Redis	SPRING_REDIS_PASSWORD ≠ REDIS_PASSWORD
Fallo de autenticación de Mongo	URL_MONGO incoherente con .env_mongo

---

Para el entorno de producción con escalado y alta disponibilidad, consulte el formato Kubernetes.