By default, a container that crashes stays dead, and nothing restarts after the server reboots. Restart policies tell the Docker daemon what to do when a container exits — the simplest way to keep services running on a VPS without extra tools.

The four policies

Policy Restarts after crash Starts after daemon/host restart After you docker stop it
no (default) No No Stays stopped
on-failure[:N] Only if exit code ≠ 0 (optionally max N tries) Yes, if it was running Stays stopped
always Yes Yes, even if you stopped it Restarts when the daemon restarts
unless-stopped Yes Yes, unless you stopped it Stays stopped

For most long-running services, unless-stopped is the right choice: it survives crashes and reboots, but respects a manual docker stop.

always differs in one way: a container you stopped by hand comes back after a reboot or a Docker restart. That’s useful for things that must never stay down; surprising for things you stopped on purpose.

Setting a policy

With docker run:

docker run -d --restart unless-stopped --name web nginx:stable
docker run -d --restart on-failure:5 --name worker myworker

In Docker Compose:

services:
  web:
    image: nginx:stable
    restart: unless-stopped
  migrate:
    image: myapp
    command: ["npm", "run", "migrate"]
    restart: "no"          # quoted: bare no is a YAML boolean

Changing the policy of an existing container

No need to recreate it:

docker update --restart unless-stopped web
docker update --restart unless-stopped $(docker ps -q)      # all running containers

Check a container’s policy:

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

Make sure Docker itself starts at boot

Restart policies only work if the daemon starts:

sudo systemctl enable docker
systemctl is-enabled docker

Package installs on Ubuntu and Debian enable it automatically.

How restarts behave

  • Docker waits a little between restarts, doubling the delay each time (100 ms, 200 ms, 400 ms…, up to a maximum), so a crash-looping container doesn’t hammer the system. The delay resets once a container has run successfully for 10 seconds.
  • A restart policy only takes effect after the container has started successfully once. A container that fails immediately on its first start isn’t restarted.
  • docker ps shows Restarting (1) 5 seconds ago for a container in a crash loop. Find the cause with docker logs.

Restart policies vs health checks

A restart policy reacts when the main process exits. If the app hangs but the process stays alive, Docker sees nothing wrong. Health checks detect that state (docker ps shows unhealthy), but plain Docker doesn’t restart unhealthy containers automatically — Swarm and Kubernetes do. Options on a single server:

  • Make the app exit on fatal errors so the restart policy can do its job.
  • Use a small watcher (e.g. the autoheal container) that restarts containers marked unhealthy.
  • Monitor from outside with Uptime Kuma to get alerted.

See Docker health checks.

Restart policy vs systemd

You could wrap each container in a systemd unit instead. Docker’s built-in policies are simpler and enough for most cases. systemd units make sense when containers must start in a strict order with non-Docker services, or when you use Podman (which integrates with systemd natively via Quadlet).

Common questions

My containers didn’t come back after a reboot. Check the policy (docker inspect), that Docker is enabled at boot, and — for unless-stopped — that you hadn’t stopped them manually before the reboot.

docker compose down and policies. down removes containers, so there’s nothing to restart. Use docker compose stop to stop while keeping them, and docker compose up -d to bring the stack back.

A container keeps restarting. That’s the policy working; the app is crashing. Look at docker logs --tail 100 NAME and the exit code with docker inspect -f '{{.State.ExitCode}}' NAME. Exit code 137 often means out of memory.

  • Web apps, databases, proxies, workers: unless-stopped.
  • Batch jobs and one-off tasks: no (or on-failure:3 for retries).
  • Critical infrastructure you never stop by hand: always.

Next: Docker logs and the Docker Compose tutorial. On a Docker VPS, restart policies are all you need to keep a self-hosted stack running through reboots and updates.

  • Docker
  • Containers
  • Reliability