Understanding Docker’s Automatic Container Startup Behavior: How dockerd Determines Which Containers to Launch on Service Restart


8 views

When you execute service docker restart on Ubuntu, Docker doesn't randomly select containers to start. The behavior is controlled by specific mechanisms that determine which containers should automatically restart.

Docker doesn't start images automatically - it starts containers. The distinction is crucial. The automatic startup behavior is determined by:

1. Container restart policies
2. The presence of containers in 'Up' state before service stop
3. Systemd/docker.socket activation (if configured)

These files control the behavior:

/var/lib/docker/containers/*/hostconfig.json
/var/lib/docker/containers/*/config.v2.json

To see which containers are configured for automatic restart:

docker inspect --format '{{.Name}} - {{.HostConfig.RestartPolicy.Name}}' $(docker ps -aq)

Example output might show:

/web_server - always
/database - unless-stopped
/test_container - no

To change a container's restart policy:

docker update --restart=always container_name
docker update --restart=no container_name

This is often the confusing policy. Containers with unless-stopped will:

  • Start automatically if Docker restarts
  • Not start if you manually stopped them (docker stop)

Docker maintains container states in:

/var/lib/docker/containers/*/checkpoints
/var/lib/docker/containers/*/state.json

To prevent specific containers from auto-starting:

# First find the container ID
docker ps -a

# Then update its restart policy
docker update --restart=no container_id

If using systemd (common on Ubuntu), check:

systemctl cat docker.service
journalctl -u docker.service

Some distributions modify default Docker behavior through systemd unit files.

For testing purposes, you can completely reset the state:

service docker stop
rm -rf /var/lib/docker/containers/*
service docker start

Warning: This will remove all container metadata.

If managing multiple containers, consider Docker Compose which offers explicit control:

version: '3'
services:
  web:
    image: nginx
    restart: unless-stopped
  db:
    image: postgres
    restart: no

The fundamental confusion here stems from mixing up images and containers. Docker doesn't automatically start images - it starts containers that were created from those images. When you run docker images, you're seeing your image repository, not running instances.

Docker uses two primary mechanisms to determine which containers should start automatically:

  1. Restart Policies: Configured per-container during creation or modification
  2. Systemd Integration: When running as a system service (common on Ubuntu)

To see which containers are set to auto-start, run:

docker ps -a --filter "status=restarting"

Or to see all containers with restart policies:

docker inspect --format '{{.Name}} {{.HostConfig.RestartPolicy.Name}}' $(docker ps -aq)

These are the typical restart policy values you'll encounter:

  • no: Never restart automatically (default)
  • on-failure: Restart only if container exits with error
  • always: Always restart (what you're likely seeing)
  • unless-stopped: Like always, but respects manual stops

To modify a container's restart policy:

docker update --restart=no container_name_or_id

Or during container creation:

docker run -d --restart unless-stopped my_image

On Ubuntu, some containers might be managed directly by systemd. Check for related services:

systemctl list-units --type=service | grep docker

Docker stores this information in:

  • /var/lib/docker/containers/ - Container configurations
  • /etc/docker/daemon.json - Global Docker settings
  • Systemd service files in /etc/systemd/system/

To find all containers with "always" restart policy:

docker inspect -f '{{if eq .HostConfig.RestartPolicy.Name "always"}}{{.Name}}{}' $(docker ps -aq)

Then disable auto-start for a specific container:

docker update --restart=no my_container