Start containers automatically

Page options

Table of contents

Docker providesrestart policiesto control whether your containers start automatically when they exit, or whenDocker restarts. Restart policies start linked containers in the correct order.Docker recommends that you use restart policies, and avoid using processmanagers to start containers.

Restart policies are different from the--live-restore flag of thedockerdcommand. Using--live-restore lets you to keep your containers running duringa Docker upgrade, though networking and user input are interrupted.

Use a restart policy

To configure the restart policy for a container, use the--restart flagwhen using thedocker run command. The value of the--restart flag can beany of the following:

Flag	Description
`no`	Don't automatically restart the container. (Default)
`on-failure[:max-retries]`	Restart the container if it exits due to an error, which manifests as a non-zero exit code. Optionally, limit the number of times the Docker daemon attempts to restart the container using the`:max-retries` option. The`on-failure` policy only prompts a restart if the container exits with a failure. It doesn't restart the container if the daemon restarts.
`always`	Always restart the container if it stops. If it's manually stopped, it's restarted only when Docker daemon restarts or the container itself is manually restarted. (See the second bullet listed inrestart policy details)
`unless-stopped`	Similar to`always`, except that when the container is stopped (manually or otherwise), it isn't restarted even after Docker daemon restarts.

The following command starts a Redis container and configures it to alwaysrestart, unless the container is explicitly stopped, or the daemon restarts.

$ docker run -d --restart unless-stopped redis

The following command changes the restart policy for an already runningcontainer namedredis.

$ docker update --restart unless-stopped redis

The following command ensures all running containers restart.

$ docker update --restart unless-stopped$(docker ps -q)

Restart policy details

Keep the following in mind when using restart policies:

A restart policy only takes effect after a container starts successfully. Inthis case, starting successfully means that the container is up for at least10 seconds and Docker has started monitoring it. This prevents a containerwhich doesn't start at all from going into a restart loop.
If you manually stop a container, the restart policy is ignored until theDocker daemon restarts or the container is manually restarted. This preventsa restart loop.
Restart policies only apply to containers. To configure restart policies forSwarm services, seeflags related to service restart.

Restarting foreground containers

When you run a container in the foreground, stopping a container causes theattached CLI to exit as well, regardless of the restart policy of thecontainer. This behavior is illustrated in the following example.

Create a Dockerfile that prints the numbers 1 to 5 and then exits.

FROM busybox:latestCOPY --chmod=755 <<"EOF" /start.shecho"Starting..."for i in$(seq1 5);doecho"$i"  sleep1doneecho"Exiting..."exit1EOFENTRYPOINT /start.sh

Build an image from the Dockerfile.
$ docker build -t startstop .
Run a container from the image, specifyingalways for its restart policy.
The container prints the numbers 1..5 to stdout, and then exits. This causesthe attached CLI to exit as well.
$ docker run --restart always startstopStarting...12345Exiting...$

Runningdocker ps shows that is still running or restarting, thanks to therestart policy. The CLI session has already exited, however. It doesn'tsurvive the initial container exit.

$ docker psCONTAINER ID   IMAGE       COMMAND                  CREATED         STATUS         PORTS     NAMES081991b35afe   startstop   "/bin/sh -c /start.sh"   9 seconds ago   Up 4 seconds             gallant_easley

You can re-attach your terminal to the container between restarts, using thedocker container attach command. It's detached again the next time thecontainer exits.
$ docker container attach 081991b35afe45Exiting...$

Use a process manager

If restart policies don't suit your needs, such as when processes outsideDocker depend on Docker containers, you can use a process manager such assystemd orsupervisor instead.

Warning
Don't combine Docker restart policies with host-level process managers,as this creates conflicts.

To use a process manager, configure it to start your container or service usingthe samedocker start ordocker service command you would normally use tostart the container manually. Consult the documentation for the specificprocess manager for more details.

Using a process manager inside containers

Process managers can also run within the container to check whether a process isrunning and starts/restart it if not.

Warning
These aren't Docker-aware, and only monitor operating system processes withinthe container. Docker doesn't recommend this approach, because it'splatform-dependent and may differ between versions of a given Linuxdistribution.

Edit this page

Request changes