Configurar correctamente los reinicios de contenedores Docker

Qué cubre este artículo sobre reinicios de contenedores

• Qué políticas de reinicio existen.
• Diferencias entre always, unless-stopped y on-failure.
• Cómo establecer políticas en Compose.
• Cuándo tiene sentido cada política.
• Errores típicos y sus soluciones.

Introducción: Configurar correctamente los reinicios de contenedores Docker

En entornos de producción, los contenedores deben reiniciarse automáticamente después de un fallo, un reinicio del servidor o un error. Docker ofrece para esto las llamadas políticas de reinicio. Estas definen cuándo y cuántas veces se reinicia un contenedor. Sin embargo, una política incorrecta puede hacer que un contenedor defectuoso intente iniciarse infinitamente o cause reinicios no deseados.

Este artículo muestra cómo aplicar las políticas de reinicio correctamente.

Conceptos importantes

• Política de reinicio: Comportamiento al detener el contenedor.
• always: El contenedor siempre se reinicia, incluso después de un reinicio.
• unless-stopped: Se reinicia a menos que el contenedor haya sido detenido manualmente.
• on-failure: Solo en caso de errores.
• no: Sin reinicio automático.
• restart_delay: Tiempo de espera entre reinicios.
• max-retries: Intentos máximos para on-failure.
• exit code: Código de retorno del proceso.

Políticas de reinicio disponibles

Política	Descripción
no	Nunca reiniciar automáticamente.
on-failure	Reiniciar si el código de salida no es 0.
always	Siempre reiniciar, incluso después del reinicio del servidor.
unless-stopped	Siempre reiniciar, a menos que esté detenido manualmente.

always

services:
  app:
    image: nginx
    restart: always

Útil para servicios que deben ejecutarse inmediatamente después de un reinicio. Atención: el contenedor se reinicia incluso después de docker stop si el daemon de Docker se reinicia.

unless-stopped

services:
  app:
    image: nginx
    restart: unless-stopped

La mejor opción para la mayoría de homelabs. El contenedor se reinicia después de un reinicio del sistema, pero no si ha sido detenido explícitamente.

on-failure

services:
  app:
    image: mein-app
    restart: on-failure
    deploy:
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3

Útil para trabajos por lotes o aplicaciones donde los reinicios después de un éxito no son deseados.

no

services:
  app:
    image: mein-app
    restart: "no"

Para tareas únicas, pruebas o depuración.

En Compose

services:
  web:
    image: nginx
    restart: unless-stopped
  db:
    image: postgres
    restart: always

Docker Run

docker run -d --name web --restart unless-stopped nginx

Verificar el contador de reinicios

docker ps -a

Con docker inspect:

docker inspect --format='{{.RestartCount}}' <container>

Evitar reinicios infinitos

• Utilizar healthchecks.
• Establecer max_attempts.
• Encontrar la causa del error en lugar de reintentar ciegamente.
• Usar on-failure en lugar de always para aplicaciones no confiables.

Ejemplo: Base de datos y aplicación

services:
  db:
    image: postgres:16
    restart: always
    environment:
      POSTGRES_PASSWORD: geheim
    volumes:
      - db_data:/var/lib/postgresql/data

  app:
    image: mein-app
    restart: unless-stopped
    depends_on:
      - db
    ports:
      - "3000:3000"

volumes:
  db_data:

Reinicio después de actualización del sistema

sudo systemctl enable docker

Asegura que Docker se inicie al arrancar, y con ello también los contenedores con always o unless-stopped.

Consejos

• unless-stopped como estándar para la mayoría de servicios.
• always para infraestructura crítica como bases de datos.
• on-failure para trabajos que no deben ejecutarse continuamente.
• Nunca always para contenedores rotos, causa bucles de arranque.
• Monitorear logs para encontrar razones de reinicio.
• Usar depends_on para controlar el orden de inicio.

Tropiezos típicos

• always pero aún así no se inicia: El daemon de Docker no se ejecuta al arrancar.
• Bucle infinito: El contenedor falla inmediatamente, always lo reinicia.
• unless-stopped se reinicia de todas formas: El sistema fue reiniciado, no detenido manualmente.
• Dependencias: La base de datos aún no está lista, la aplicación se reinicia.
• Código de salida incorrecto: La aplicación termina con 0, on-failure no se activa.

Enlaces e información adicional

• BotServ.de Docker Compose
• BotServ.de Docker Healthchecks
• BotServ.de Docker Logs
• BotServ.de Docker Log-Rotation

Preguntas frecuentes: Reinicios de contenedores Docker

¿Cuál es la diferencia entre always y unless-stopped? always se reinicia incluso después de docker stop si el daemon se reinicia. unless-stopped no se reinicia si el contenedor fue detenido previamente.

¿Se reinicia unless-stopped después de un reinicio del sistema? Sí, siempre que el contenedor no haya sido detenido manualmente.

¿Cómo evito reinicios infinitos? Usar on-failure con max_attempts o corregir errores en los logs.

¿Cuándo debo usar no? Para trabajos únicos, pruebas o depuración.

¿Puedo configurar el retraso entre reintentos? Sí, en Compose con deploy.restart_policy.delay.

Fuentes y lecturas adicionales

• Docker Restart Policies: https://docs.docker.com/config/containers/start-containers-automatically/
• Compose Restart: https://docs.docker.com/compose/compose-file/05-services/#restart

Resumen: Configurar correctamente los reinicios de contenedores Docker

Las políticas de reinicio aseguran que los contenedores se ejecuten automáticamente después de errores o reinicios del sistema. Para la mayoría de homelabs y entornos de producción, unless-stopped es la mejor opción, ya que permite reinicios después de reinicios del sistema pero respeta las detenciones manuales. always es apropiado para servicios críticos, on-failure para trabajos por lotes. Quienes deseen evitar reinicios infinitos deben utilizar healthchecks, max_attempts y logs limpios.