Despliega Next.js detrás de Traefik con TLS automático

Subir una app de Next.js a un servidor suena trivial hasta que te topas con las tres cosas que de verdad cuestan tiempo: enrutar un dominio al contenedor correcto, conseguir un certificado TLS real sin tener que renovarlo a mano, y no exponer sin querer el puerto de tu app a todo internet. Esta guía recorre el patrón exacto que uso en ilustrari.com (Traefik al frente, un contenedor por app, Let's Encrypt en piloto automático) y te explica el porqué de cada pieza para que puedas depurarlo cuando, no si, algo se ponga raro. Al final vas a tener un dominio sirviendo HTTPS, un certificado que se renueva solo y una app cuya única puerta al exterior es el proxy.

Esto es un tutorial y un por qué a la vez. Te dejo config lista para copiar y pegar, pero también te digo qué label hace el trabajo de verdad y dónde se esconden las fallas más comunes. Si alguna vez peleaste con un 404 de un reverse proxy o viste un challenge de ACME quedarse colgado hasta el timeout, la idea es que eso deje de ser un misterio.

01 · Requisitos previos y el modelo mental

Antes de tirar un solo comando, ten claro el modelo, porque explica cada decisión de config que viene después. El servidor hace exactamente dos trabajos. Corre un reverse proxy (Traefik) que es dueño de los puertos 80 y 443 y termina el TLS de todo. Y corre un contenedor por app, y ninguno publica un puerto al host. El proxy es el único proceso con el que internet habla; la app vive en una red privada de Docker y, vista desde afuera, es invisible.

Primero necesitas tener unas cuantas cosas en su sitio:

1. Un VPS al que puedas entrar por SSH, con Docker y el plugin de Docker Compose instalados.
2. Un dominio, con un registro A apuntando a la IP pública del VPS. Esto tiene que resolver antes de desplegar, porque el challenge HTTP-01 de Let's Encrypt falla si el nombre todavía no apunta a la máquina.
3. Los puertos 80 y 443 abiertos en el firewall y sin que ningún otro proceso los esté ocupando.
4. Traefik ya corriendo con un resolver ACME (Let's Encrypt) y una red externa de Docker. A lo largo de la guía doy por hecho que el resolver se llama le y la red se llama edge, así que ajústalo a lo que tu Traefik use de verdad.

Si todavía no tienes Traefik corriendo, móntalo una sola vez como su propio proyecto de Compose, dueño de la red edge y del resolver ACME; de ahí en adelante cada app solo se engancha. El resto de la guía asume que ese setup inicial ya está hecho.

02 · Un Dockerfile liviano y sin root

Una imagen de Next.js hecha a la ligera termina siendo enorme y corre como root. Las dos cosas se arreglan en un solo Dockerfile multi-stage. La clave es el modo de output standalone de Next.js, que rastrea exactamente los archivos que la app necesita en runtime y te deja enviar una imagen runner sin el árbol completo de node_modules.

Primero, actívalo en tu config de Next.js:

// next.config.ts
import type { NextConfig } from 'next'

const config: NextConfig = {
  output: 'standalone',
}

export default config

Después el Dockerfile hace el build en una etapa y corre en otra etapa liviana y sin privilegios:

# etapa de build
FROM node:22-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# etapa de runtime
FROM node:22-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
RUN addgroup -S app && adduser -S app -G app
COPY --from=builder /app/public ./public
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
USER app
EXPOSE 3000
CMD ["node", "server.js"]

Vale la pena señalar algunas decisiones. La etapa de build carga toda la toolchain y las dependencias; la de runtime copia solo el output rastreado, así que la imagen final pesa una fracción. La línea EXPOSE 3000 es documentación y cableado interno de la red. No publica el puerto al host. Y correr como el usuario sin privilegios app significa que, si alguien compromete el contenedor, no arranca con permisos de root.

03 · El archivo de Compose y los cuatro labels que importan

Aquí tienes la app como un servicio de Compose. No hay sección ports, y esa ausencia es justamente la clave del asunto.

services:
  web:
    build: .
    restart: unless-stopped
    networks: [edge]
    labels:
      - traefik.enable=true
      - traefik.http.routers.web.rule=Host(`example.com`)
      - traefik.http.routers.web.entrypoints=websecure
      - traefik.http.routers.web.tls.certresolver=le
      - traefik.http.services.web.loadbalancer.server.port=3000
networks:
  edge:
    external: true

Lee los labels uno por uno, porque cada uno corresponde a un concepto:

• traefik.enable=true mete este contenedor en juego. Con Traefik configurado en exposed-by-default false, un contenedor se ignora hasta que diga lo contrario, un default seguro que evita exposiciones accidentales.
• routers.web.rule=Host(example.com) es la condición de match: las requests para ese hostname se enrutan aquí. Pon tu dominio. El nombre del router (web) es una clave arbitraria; mantenla única por app.
• routers.web.entrypoints=websecure amarra el router al entrypoint de HTTPS (puerto 443). No va a responder en HTTP plano a menos que le agregues un redirect, que es lo que quieres.
• routers.web.tls.certresolver=le es la línea que dispara la emisión del certificado. Traefik la ve, le pide a Let's Encrypt un cert para el host de la regla, resuelve el challenge y guarda el resultado. El certificado sale, literalmente, como efecto secundario de este único label.
• services.web.loadbalancer.server.port=3000 le dice a Traefik a qué puerto interno reenviar por la red edge. Aquí es donde vive el puerto del contenedor, no en un mapeo al host.

Por qué nada de mapeo de ports

Si pusieras ports: ["3000:3000"] abrirías un hueco en el firewall del host directo hasta la app, saltándote el TLS y Traefik por completo. Todo el modelo depende de que a la app solo se le pueda llegar a través del proxy en la red privada. Traefik se conecta al contenedor por edge usando el puerto del loadbalancer; el host nunca necesita enterarse de que el puerto 3000 existe.

04 · Levántalo y observa cómo se emite el certificado

Con el DNS resolviendo y el archivo guardado, el deploy es un solo comando:

docker compose up -d --build

Esto hace el build de la imagen y arranca el contenedor en segundo plano. Traefik detecta el contenedor nuevo en uno o dos segundos, lee sus labels y arranca el flujo de ACME para example.com. Míralo en el contenedor de Traefik, no en el de la app:

1. Corre docker logs -f traefik (usa el nombre de tu contenedor de Traefik).
2. Busca cómo arranca el challenge de ACME y luego una línea que confirme que el certificado se obtuvo para tu dominio. En un setup sano esto toma segundos.
3. Entra a https://example.com (opens in new tab) en un navegador. Deberías ver tu app sobre HTTPS con un certificado válido de Let's Encrypt y sin ninguna advertencia.
4. Confirma que el HTTP plano se comporta como esperas, por lo general un redirect a HTTPS si configuraste uno del lado de Traefik.

Un ejemplo paso a paso

Digamos que el dominio es proyeccion.example.com y Traefik ya corre con el resolver le en la red edge. Agregas el registro A, esperas a que dig +short proyeccion.example.com devuelva la IP del VPS, pones la regla Host con ese subdominio, corres docker compose up -d --build y le haces tail a los logs de Traefik. En unos segundos el cert se emite y el subdominio sirve HTTPS. Desplegar la siguiente app, digamos una segunda herramienta en agent-orchestra.example.com, son los mismos cuatro labels, con otro nombre de router y otro host. No hay que tocar ningún archivo central. Esa repetibilidad es la razón por la que el patrón escala a un puñado de apps en una sola máquina.

05 · Errores comunes y cómo leerlos

Casi todas las fallas aquí caen en un conjunto pequeño y conocido. Si identificas el síntoma, llegas directo a la causa.

• El certificado nunca se emite. Casi siempre es DNS o el puerto 80 bloqueado. El challenge HTTP-01 de ACME necesita llegar a la máquina por el puerto 80 para el dominio de la regla. Verifica que el registro A resuelva y que nada más esté ocupando el 80.
• Traefik devuelve un 404 para tu host. La regla del router no hace match, o falta traefik.enable=true, o el contenedor no está en la red edge. Revisa que se cumplan las tres cosas; un typo en la regla Host() es el sospechoso de siempre.
• 502 Bad Gateway. Traefik encontró el router pero no logra llegar a la app. El loadbalancer.server.port no coincide con el puerto donde la app escucha de verdad, o la app se cayó al arrancar. Revisa docker logs del contenedor de la app.
• La app carga pero sin estilos ni imágenes. Se te olvidó copiar public y .next/static en el Dockerfile (mira la sección 02), o la app no está en modo standalone.
• Te topas con un límite de peticiones de ACME mientras pruebas. Let's Encrypt limita la emisión de certificados por dominio. Mientras estás iterando, apunta el resolver al endpoint de staging (pruebas) de Let's Encrypt y pásalo a producción cuando el flujo te funcione de punta a punta.

Cuando redespliegas una versión nueva, la regla que te protege es simple: deja que el contenedor nuevo esté sano antes de que el viejo se apague. Haz el build, arranca la imagen nueva, confirma que responde, y deja que Compose reemplace al contenedor viejo. El estado debería vivir fuera de la máquina (en el caso de ilustrari, eso es Supabase) para que el contenedor en sí siga siendo desechable y un redeploy nunca ponga en riesgo tus datos.

Ese es todo el patrón: una app privada, un proxy público y un certificado que se cuida solo. Una vez que la primera app está arriba, cada app que venga después son los mismos cuatro labels y un comando, que es justo el punto. La repetibilidad aburrida es la ventaja. Acierta con el DNS, mantén el puerto fuera del host, y deja que Traefik se encargue de la parte que a nadie le gusta hacer a mano.