Traefik v3 en VPS: reverse proxy Docker con HTTPS automático

Por qué Traefik v3 en lugar de nginx para tu stack Docker

• Descubrimiento automático de contenedores mediante labels Docker — sin recarga manual al añadir un servicio.
• HTTPS automático con Let's Encrypt (challenge TLS-ALPN-01 o HTTP-01): certificados obtenidos, almacenados y renovados sin intervención.
• Middlewares nativos declarables por label: BasicAuth, rate-limit, cabeceras de seguridad, redirecciones — sin escribir ningún módulo nginx.
• Dashboard integrado en tiempo real: visualiza todas las rutas, middlewares y estado de los certificados desde el navegador.
• Soporte HTTP/3 (QUIC) en una sola línea de configuración: mejora el rendimiento en conexiones de alta latencia.
• Enrutamiento por Host, PathPrefix, Headers o cualquier combinación — las reglas se escriben con sintaxis expresiva de Go template.
• API REST interna: consulta el estado del enrutador, inspecciona backends activos, automatiza integraciones CI/CD.
• Compatible con Docker Swarm, Kubernetes y Nomad — migra sin cambiar tus labels.

Requisitos técnicos antes de empezar

Instalación completa de Traefik v3 paso a paso

1. 01

   Crear la red Docker compartida. Traefik debe estar en la misma red que los servicios que proxifica. Créala una sola vez: docker network create traefik-public. Esta red se referenciará en cada docker-compose.yml de tus servicios.

2. 02

   Crear el archivo acme.json para los certificados. Let's Encrypt escribirá sus certificados en este archivo. Debe pertenecer a root con permisos estrictamente 600: touch /opt/traefik/acme.json && chmod 600 /opt/traefik/acme.json. Si los permisos son incorrectos, Traefik se negará a arrancar.

3. 03

   Crear el docker-compose.yml de Traefik. Coloca el archivo en /opt/traefik/docker-compose.yml con la configuración completa: entrypoints TLS, el resolver ACME de Let's Encrypt y las labels del dashboard protegido.

4. 04

   Generar el hash BasicAuth para el dashboard. Reemplaza la cadena hardcoded por un hash bcrypt real: echo $(htpasswd -nB admin) | sed -e 's/\$/\$\$/g'. El comando htpasswd está en el paquete apache2-utils. Los signos $ deben duplicarse ($$) en los valores de labels de Docker Compose.

5. 05

   Arrancar Traefik. Desde /opt/traefik/: docker compose up -d. Verifica los logs: docker compose logs -f traefik. Debes ver "Starting provider" providerType=Docker y luego "Attaching router" routerName=dashboard.

6. 06

   Añadir un servicio detrás de Traefik. En el docker-compose.yml de tu aplicación, únete a la red traefik-public (como externa) y añade las cuatro labels clave: traefik.enable=true, la regla Host(), el entrypoint websecure, el certresolver y el puerto del backend.

7. 07

   Verificar los certificados Let's Encrypt. Inspecciona acme.json: cat /opt/traefik/acme.json | python3 -m json.tool | grep -A3 'domain'. Debes ver tus dominios con una fecha de expiración a 90 días. Alternativamente, el dashboard de Traefik lista todos los certificados activos en la pestaña *Routers*.

8. 08

   Validar la redirección HTTP→HTTPS. Prueba con curl: curl -v http://app.dominio.com. Debes recibir un 301 Moved Permanently a https://. Si obtienes conexión rechazada en el puerto 80, verifica que las reglas del firewall permiten ese puerto.

9. 09

   Activar HTTP/3 en el navegador. Añade la cabecera Alt-Svc mediante un middleware global en tus labels de Traefik. La cabecera Alt-Svc: h3=":443"; ma=86400 indica al navegador que tu servidor soporta QUIC. Verifica con curl --http3 https://app.dominio.com -v.

Middlewares esenciales: BasicAuth, rate-limit y cabeceras de seguridad

• BasicAuth en una ruta privada — para proteger una herramienta de administración (Adminer, Flower, etc.): añade las labels traefik.http.middlewares.adminauth.basicauth.users y traefik.http.routers.myadmin.middlewares=adminauth en el servicio.
• Rate-limit anti-abuso — protege una API o un formulario de contacto: configura ratelimit.average=100 (100 req/s de media) y ratelimit.burst=50 (ráfaga de 50 tolerada), luego aplica el middleware al router.
• Cabeceras de seguridad HTTP — X-Frame-Options, X-Content-Type-Options, Strict-Transport-Security: el middleware headers de Traefik acepta todos estos valores directamente como labels, sin archivo de configuración nginx separado.
• Redirect Regex — para redirigir www.dominio.com a dominio.com: usa el middleware redirectregex con permanent=true y una regex ^https://www\.(.+) → https://${1}.
• Compress — activa la compresión gzip/brotli en todas las respuestas textuales con una sola label: traefik.http.middlewares.compress.compress=true. Aplícala globalmente añadiéndola como middleware por defecto en la configuración estática.

Migración desde Traefik v2: cambios que rompen la compatibilidad

• docker.swarmMode renombrado a docker.swarmmode (todo en minúsculas). Si tu config v2 usa la casing antigua, Traefik v3 la ignora silenciosamente y el descubrimiento Swarm no funciona.
• Regla PathPrefix sin trailing slash: en v3, PathPrefix('/api') es equivalente a PathPrefix('/api/') — el trailing slash se normaliza. Si tenías reglas que dependían de este comportamiento, revísalas.
• tls.certificates en configuración dinámica: en v3, esta sección debe estar en la configuración estática (traefik.yml) o mediante un proveedor dedicado.
• Middleware errors: el parámetro query se renombra a url. Cualquier configuración que use errors.query debe actualizarse a errors.url.
• Eliminación del soporte del protocolo spiffe: si usabas autenticación SPIFFE en una infraestructura Consul, migra a una solución mTLS estándar antes de actualizar a v3.
• Configuración constraints de Docker: la sintaxis de las restricciones ha cambiado para alinearse con el formato estándar de tags Docker. Verifica tu lista de restricciones si filtrabas servicios por tag.

Traefik v3 vs nginx vs Caddy: ¿qué reverse proxy para Docker?

Desplace la tabla

Solución de problemas: los cinco errores más frecuentes

• level=error msg="Unable to obtain ACME certificate" error="acme: error 403" — Let's Encrypt no puede verificar tu dominio. Comprueba que el puerto 80 está abierto desde Internet y que el DNS de tu dominio apunta a la IP del VPS.
• level=error msg="The acme.json file has bad file permissions" y Traefik se niega a arrancar — los permisos del archivo no son 600. Corrige: chmod 600 /opt/traefik/acme.json. Este check es intencionalmente bloqueante.
• Servicio visible en el dashboard de Traefik pero error 502 Bad Gateway — el contenedor del servicio no está en la red traefik-public. Verifica con docker inspect <container> | grep -A20 Networks. Añade la red en el docker-compose.yml del servicio y recrea el contenedor.
• Labels ignoradas silenciosamente, ruta ausente del dashboard — olvidaste traefik.enable=true en el servicio, o --providers.docker.exposedbydefault=false está activo y la label está ausente.
• invalid character '$' in label value — los signos $ en los hashes BasicAuth no están duplicados en el archivo Compose. La sintaxis correcta es $$2y$$10$$... en docker-compose.yml. Si pasas el valor mediante una variable de entorno, un solo $ es suficiente.

Siguiente paso: reforzar tu stack Docker para producción