Despliegue

Todos los servicios del ecosistema usan un mismo modelo de despliegue. Esta página lo describe.

Aquí no hay detalles concretos de los hosts

Los detalles operativos — direcciones de servidor, nombres de usuario, configuración secreta — no forman parte de este sitio público. Viven en un runbook cerrado dentro del repositorio correspondiente.

El modelo general

        Internet
            │
            ▼
   ┌─────────────────┐
   │   edge nginx    │  TLS termination · HSTS · rate limit
   │   (contenedor)  │  cada vhost → un servicio interno
   └────────┬────────┘
            │  red Docker compartida
   ┌────────┴──────────────────────────────┐
   │                                       │
   ▼                ▼                      ▼
 app A            app B                sitio estático
 (Go + Next)     (Go + Next)            (nginx)
   │                │
   └────────┬───────┘
            ▼
   PostgreSQL · Redis  (compartidos)

Principios básicos:

1. Un edge, muchos vhosts. Por fuera, un único contenedor nginx posee los puertos 80/443. Cada dominio tiene su bloque server y hace proxy hacia un servicio interno.
2. Los servicios internos no están expuestos. Las aplicaciones solo escuchan en la red Docker compartida, o se enlazan a 127.0.0.1. No se puede llegar a ellas directamente desde fuera.
3. Infraestructura compartida. Una instancia de PostgreSQL y una de Redis sirven a varias aplicaciones; cada aplicación tiene su propia base o esquema.
4. Docker Compose: cada aplicación tiene su propia stack de compose, conectada a la red compartida.

El edge nginx

El edge se encarga de:

Función	Detalle
Terminación TLS	Certificados de Let's Encrypt, renovación automática
HSTS	max-age=63072000; includeSubDomains
Rate limit	Por zonas: auth (estricta) · app (laxa) · api
Proxy inverso	vhost → servicio interno
Rechazo de hosts desconocidos	Default server → cortar la conexión

La configuración del edge se gestiona por git

El directorio conf.d del edge nginx se sincroniza desde un repositorio concreto mediante git. Cualquier edición manual en el host quedará sobrescrita por git reset --hard en el siguiente despliegue.

Por eso añadir o cambiar un vhost se hace haciendo commit en el repositorio, y la CI se encarga de distribuirlo.

Un segundo modelo: que el servicio posea su propio vhost

También existe el modelo en que un vhost que solo atañe a un servicio reside en el repositorio de ese servicio y no en un fichero central, y su despliegue instala la configuración en el conf.d del edge como fichero aparte.

La ventaja: el cambio se completa dentro de un único repositorio y no espera al despliegue de otro equipo. La condición: la configuración debe ser totalmente autónoma — no puede depender de una zona de rate-limit ni de un default server definidos en otro fichero.

Este sitio funciona justamente así — véase Esta plataforma documental.

Certificados

• Let's Encrypt, con certbot en modo webroot.
• El desafío ACME se sirve por el puerto 80 en /.well-known/acme-challenge/.
• La renovación es automática, semanal por cron; si tiene éxito se recarga nginx.

Para añadir un dominio nuevo:

1. Apunte el DNS al servidor.
2. Añada el dominio al bloque ACME del puerto 80.
3. Obtenga el certificado con certbot.
4. Añada el vhost HTTPS y apúntelo al certificado.
5. Ejecute nginx -t y recargue.

Sitios estáticos (portales de documentación)

Los sitios de documentación son HTML estático construido de antemano. La forma más sencilla de servirlos:

• construir site/ con MkDocs,
• copiar el resultado al servidor,
• servirlo con un pequeño contenedor nginx:alpine,
• que el edge nginx haga proxy hacia él.

No hay runtime de aplicación, así que se consumen pocos recursos y hay poco que se pueda romper.

Este sitio funciona exactamente así — véase Esta plataforma documental para el detalle.

Despliegue de aplicaciones

Para las aplicaciones conviven dos modelos:

Modelo	Detalle
Build en el host	La CI sincroniza el repositorio en el host y ejecuta docker compose build && up -d
Vía registry	La CI construye la imagen y la sube a un registry; el host hace pull && up -d

La tendencia va hacia reducir dependencias: hay casos que pasaron de un registry externo a construir en el propio host.

Despliegue parcial: la CI determina qué servicios reconstruir a partir de las rutas modificadas (paths-filter). Un cambio en una aplicación no altera las demás.

Rollback

• Sitio estático — descomprimir el archivo de la construcción anterior.
• Aplicación — volver al tag de imagen anterior (se puede fijar con la variable <SVC>_IMAGE_TAG).

Comprobaciones de salud

Cada servicio tiene un endpoint /health. Los healthcheck de compose verifican que la infraestructura (PostgreSQL, Redis) esté lista y arrancan la aplicación solo después.

Lista de comprobación del despliegue

• [ ] DNS apuntado correctamente
• [ ] Certificado emitido y cubierto por la renovación automática
• [ ] Vhost del edge añadido y con commit en el repositorio
• [ ] nginx -t pasa correctamente
• [ ] Servicios internos no expuestos al exterior
• [ ] /health responde
• [ ] Secretos por variables de entorno, ausentes del repositorio
• [ ] Método de rollback claro

Para el detalle de la automatización, véase CI/CD.