Complete Guide to Docker Container Auto-Start Configuration

This guide will show you how to set up Docker containers to start automatically when your system boots. To make containers auto-start, you need two things: Docker service must start on boot, and then set the right restart policy for your containers. Once you do this, your containers will start up automatically after a reboot.

Getting Docker Service to Start on Boot

Your containers need the Docker daemon running to work. If the daemon isn’t running, no containers can start. So the first step is making sure the Docker daemon starts automatically when your host machine boots up.

Linux with systemd

Most production Linux distributions (like Ubuntu, CentOS, RHEL) use systemd as their init system and service manager. Setting up Docker to start automatically is pretty standard practice.

• Core command: The main command to enable Docker service is sudo systemctl enable docker.service. This creates a symbolic link in systemd’s configuration that tells the system to start Docker during the boot process.

• Related services: Docker Engine depends on containerd as its underlying container runtime. That’s why the official docs recommend enabling the containerd service too, to make sure the complete runtime stack is available: sudo systemctl enable containerd.service.

• Manual control and verification: You can manually start the service with sudo systemctl start docker, or temporarily disable auto-start with sudo systemctl disable docker.service when you need maintenance or troubleshooting.

• Special scenarios (WSL & Docker Desktop for Linux): For developers using Docker in Windows Subsystem for Linux (WSL), systemd might not be enabled by default. One solution is to modify the /etc/wsl.conf file to enable systemd. For users running Docker Desktop on Linux, the auto-start is managed by user-session level systemd services with the command: systemctl --user enable docker-desktop.

It’s important to note that this achieves “start when user logs in,” not true “start when server boots,” which is typically what you want for headless server environments.

Windows and macOS Auto-Start with Docker Desktop

In Windows and macOS development environments, auto-start functionality is configured through Docker Desktop’s graphical interface.

• Configuration path: In Docker Desktop’s “Settings” menu under the “General” tab, you’ll find a checkbox for “Start Docker Desktop when you sign in to your computer.” Check this box to enable automatic startup when you log in.

• Common troubleshooting: Sometimes this setting might not work. The usual causes involve corrupted configuration files (settings.json) or OS-level permission issues. You can manually check the config file for diagnosis. On macOS, the path is ~/Library/Group Containers/group.com.docker/settings.json; on Windows, it’s %APPDATA%\Docker\settings.json.

• Key difference: This feature is “start on login,” mainly designed for developers. If you need true unattended boot startup on Windows Server, you’ll need alternative solutions like Windows Task Scheduler.

Docker Container Restart Policies

The simplest way to set up auto-start is to add the --restart parameter when running docker run:

docker run -d \
  --name myapp \
  --restart=always \
  nginx:latest

Understanding restart Parameters

no - Complete Manual Control (Default)

This is Docker’s default policy. When a container exits, regardless of the reason, Docker won’t automatically restart it.

• Use cases: This policy is perfect for short-lived tasks like one-time database migrations, batch jobs, or data analysis scripts. It’s also great during development and debugging because it lets you examine the container’s final state after it exits without automatic restarts getting in the way.

on-failure: Recovering from Errors

This only restarts the container when it exits with a non-zero exit code. In Docker and Unix-like systems, exit code 0 means success, while any non-zero value indicates an error occurred. This policy won’t trigger restarts when containers complete successfully (exit code 0) or when the Docker daemon restarts.

• Limiting retry attempts: A key feature of the on-failure policy is that you can limit maximum retries using the :max-retries suffix, like --restart on-failure:5. This mechanism acts as an important “circuit breaker” to protect host stability. It prevents a misconfigured or buggy container from getting stuck in an endless crash-restart loop that could exhaust host resources.

• Use cases: Good for tasks that might occasionally fail but shouldn’t run continuously. For non-critical applications or apps with unpredictable failures, this is a safer choice than always because it prevents resource exhaustion through retry limits.

always: Maximum Availability

The always policy tries to restart the container no matter what exit code it stops with. When the Docker daemon starts (like after a host reboot), it will also start all containers using this policy.

If you manually stop a container using docker stop or docker kill commands, its always restart policy gets temporarily ignored until the Docker daemon restarts or you manually start the container (docker start). This is intentional design by Docker to prevent administrators from getting into a “tug-of-war” with restart policies during maintenance.

• Use cases: Best for critical services that need to run continuously, like web servers, databases, message queues, or background workers where availability is crucial.

unless-stopped: Persistent Running with Manual Override

This policy is very similar to always - it restarts the container when it stops for any reason. However, the key difference is: if a container is explicitly stopped (whether manually with docker stop or by other processes sending stop signals), it won’t automatically restart even when the Docker daemon restarts. The policy only becomes active again after the container is manually started.

• Policy comparison: unless-stopped is often considered the best choice for most production services. It provides high availability similar to always, while respecting administrator intentions by allowing services to stay offline for maintenance or troubleshooting.

• Use cases: Ideal for services that should always run but might need temporary downtime for maintenance or upgrades. Administrators can confidently stop services without worrying about them accidentally auto-starting during the next host reboot.

Built-in Backoff Mechanism: Preventing Restart Loops

To prevent rapidly failing containers from overwhelming the system, Docker has a built-in elegant backoff mechanism.

• Behavior: When a container needs to restart, Docker doesn’t do it immediately. Instead, it introduces an exponentially growing delay. This delay starts at 100 milliseconds and doubles with each restart attempt until it reaches an upper limit. This mechanism is similar to the “exponential backoff algorithm” used in network communications, effectively preventing containers stuck in “crash loops” from exhausting Docker daemon and host resources.

• Reset after successful start: Restart policies only fully take effect after a container “successfully starts.” Here, “successful start” means the container runs for at least 10 seconds. Once a container meets this condition, the exponential backoff delay counter gets reset. This design prevents containers that fail during initialization (like due to configuration errors) from entering endless restart attempts.

• Analogy to Kubernetes CrashLoopBackOff: This concept is fundamentally similar to Kubernetes’ well-known CrashLoopBackOff state. While CrashLoopBackOff is a native Kubernetes state, the core idea it represents - gracefully handling restart loops by adding delays to provide time for system recovery and human intervention - is completely consistent with Docker’s built-in backoff mechanism.

Docker Container Restart Policy Comparison

Summary

To make Docker containers automatically run when your system starts, you need to do two things: first, make the Docker service start with your host, and second, set appropriate restart policies for containers that need auto-start.

Choosing a restart policy isn’t just a technical configuration - you need to find the right balance between availability, stability, and security. The always and unless-stopped policies provide the highest availability, but without limits, they might consume too many resources when containers fail. The on-failure policy, especially when used with maximum retry counts, acts as a “circuit breaker” to protect overall host stability.