docker

Cómo reiniciar automáticamente contenedores Docker

Qué son las restart policies de Docker, sus diferencias (no, on-failure, always, unless-stopped) y cómo aplicarlas con docker run y docker update.

16 de septiembre de 2026·10 min de lectura

Cuando un proceso dentro de un contenedor termina, el contenedor se detiene. Con una restart policy (política de reinicio) le dices a Docker qué debe hacer en ese caso: dejarlo parado, volver a lanzarlo o decidirlo según el código de salida. Es la forma nativa de conseguir cierta resiliencia sin instalar nada extra.

Esta guía asume que tienes Docker instalado y un contenedor de prueba para experimentar.

Qué es una restart policy

Es una configuración que guarda Docker junto al contenedor (no es algo del proceso interno). Hay cuatro políticas y, opcionalmente, un límite de reintentos:

Política Comportamiento
no Nunca reinicia automáticamente. Es el valor por defecto.
on-failure Reinicia solo si el proceso termina con un código de salida distinto de cero (un fallo real).
always Reinicia siempre que el contenedor se detenga, sin importar el motivo o el código de salida.
unless-stopped Igual que always, salvo que el contenedor se haya detenido explícitamente con docker stop.

Las dos que más se usan en producción son always (o unless-stopped) y on-failure. La diferencia clave está en quién cree el motivo de la parada:

  • on-failure intenta detectar que la app falló (proceso muerto con error).
  • always y unless-stopped no distinguen: Docker reinicia el contenedor, y es tu docker stop el único “parón limpio” que no se re-lanza (en el caso de unless-stopped).

Crear un contenedor con --restart

El flag --restart se pasa en el momento de crearlo:

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

Con esto, si el proceso de Nginx se cuelga o crashea, Docker lo arranca de nuevo automáticamente.

on-failure admite un límite de reintentos separado por dos puntos. Útil para contenedores que no deben lanzarse en bucle infinito:

docker run -d --name worker --restart on-failure:5 busybox sh -c "exit 1"

Aquí, tras 5 intentos fallidos consecutivos, Docker deja de releventar el contenedor.

Nota: reiniciar el contenedor no reinicia los procesos hijos colgados ni resuelve la causa raíz del fallo. Es una red de seguridad, no un arreglo.

Modificar la política de un contenedor existente

No necesitas recrear el contenedor. Con docker update cambias la política en caliente:

docker update --restart unless-stopped web

También funciona para ajustar el límite de reintentos:

docker update --restart on-failure:10 worker

Comprobar la configuración actual

docker inspect muestra el namespace de la política y el límite de intentos:

docker inspect --format '{{.HostConfig.RestartPolicy.Name}}' web

Debe imprimir unless-stopped (o la política que hayas elegido). Para ver el contador de reintentos:

docker inspect --format '{{.HostConfig.RestartPolicy.MaximumRetryCount}}' web

Comportamiento tras reiniciar el servidor

Cuando se reinicia el daemon de Docker (por ejemplo, al reiniciar el servidor), se aplican las mismas reglas:

  • no o on-failure: el contenedor no se re-lanza (salvo que on-failure tuviera un fallo pendiente de reintentar; en la práctica se considera “no arranca solo”).
  • always: el contenedor vuelve a arrancar siempre, incluso si lo habías detenido con docker stop.
  • unless-stopped: arranca de nuevo excepto si lo habías detenido explícitamente con docker stop.

Por eso unless-stopped es la opción habitual para servicios: te deja respetar docker stop (mantenimiento, tareas nocturnas) sin que el propio sistema te lo deshaga, pero arranca lo que debía estar corriendo cuando la máquina se reinicia de verdad.

Diferencia entre reinicio manual y automático

Haz la prueba:

docker stop web
docker inspect --format '{{.HostConfig.RestartPolicy.Name}}' web   # sigue en unless-stopped
docker logs web

Cuando detienes un contenedor a mano, Docker no lo relanza de inmediato aunque la política sea always: respeta tu orden. El reinicio automático aplica a las paradas no iniciadas por ti (crash del proceso, muerte del daemon, reinicio del servidor). Es la diferencia esencial entre el mantenimiento consciente y el fallo real.

Ejemplo práctico

Levanta un servicio que se reinicie automáticamente como prueba:

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

# Tras apagar el daemon (en un entorno de pruebas) y volver a arrancarlo:
systemctl restart docker   # o: sudo service docker restart
docker ps                  # 'web' vuelve a estar Up

Si además quisieras ver si algo se reinicia en bucle, los logs del contenedor son el primer lugar al que mirar; en este blog tienes la guía de cómo ver los logs de un contenedor Docker.

Cuándo NO usar reinicio automático

  • Tareas por lotes o de una sola ejecución (cron jobs, migraciones): un script que termina con código 0 no debe relanzarse. Usa no.
  • Apps que necesitan intervención humana: si cada fallo requiere revisión (p. ej. después de una migración), un bucle de reintentos solo enmascara el problema.
  • Servicios con estado y datos (bases de datos, colas): reiniciar un proceso que se cerró a medias antes de revisar los logs puede corromper más que arreglar. Aquí prima “cómo recupero los datos”, y para eso conviene planificar un backup de volúmenes Docker.
  • Procesos que tienen su propio supervisor: meter una política de Docker sobre algo que ya se auto-reinicia solo provoca cascadas de reinicios.

Errores comunes

no restart policy aunque puse --restart

Verifica el nombre del contenedor y que el flag se pasó en la creación:

docker inspect --format '{{.HostConfig.RestartPolicy.Name}}' mi-contenedor

Si ves no, modifícala con docker update --restart always, --restart unless-stopped o --restart on-failure, según lo que quieras. Recuerda: docker run define la política en la creación; cambiar la doc no cambia contenedores que ya existen.

El contenedor se reinicia en bucle

Si docker ps muestra estados Restarting (...), la política always/on-failure encontró un fallo repetido. Mira los logs para dar con la causa:

docker logs --tail 50 mi-contenedor

Y si quieres cortar el bucle mientras reparas, detenlo y apunta 0 reintentos:

docker update --restart no mi-contenedor

Conclusión

Elegir bien la restart policy requiere saber qué hace tu proceso cuando muere. unless-stopped cubre la mayoría de los servicios que quieres “siempre arriba”, on-failure evita relanzar procesos que terminan bien, y no es correcto para lo puntual. La política es un complemento, no un sustituto de revisar los logs y de tener un plan de recuperación de datos.

← Volver a tutoriales