Docker for Beginners - Docker Container Restart Policies

Docker Posted 11 months ago

In a previous article, we have spoken in length about what a docker compose is, and how it can help us in creating customized image builds with high levels of sophistication and build time configurations. A typical docker-compose file so far we have seen would generally contain the services which need to be built along with their respective Dockerfile paths which will be used in building these services. Within these services we specify which ports to take, volumes if needed along with other docker image specific configurations. In this article let's talk about how we can also specify how these images when containerized should behave when struck with a termination, aka their "restart" behavior expectations.


Restart Policies are single value specifications which describe how a container should behave in case if it stops execution due to an error or a manual intervention. When in production, applications can come across a variety of scenarios which may not be covered by integration tests or staging environments. Be it loads or external dependencies or even uncovered bugs, an application might run into issues can can terminate owing to these. When an application stops abruptly for any reason, it could create a lot of trouble and is strictly unwanted for production grade application instances. These Restart Policies provide instructions for the applications about how they should behave during such situations. This is a single value specified among a set of options, which provide different behaviors accordingly.

It is a good practice for a developer to specify a restart policy for a service based on what kind of service is being dealt with. For services such as web services or data servers, it is always mandatory to come back quickly from a down time, while for web applications or API it may not be that important. Hence it boils down to the kind of service is being created, to be assigned a restart policy.

A restart policy is specified in a docker-compose as below:

-- docker-compose.yaml --

#version of docker-compose#
version: '3'

#containers which are being built and run#
    #container name to be used while creating#
        #the path of dockerfile to be used#
        build: .
        #the ports on which the container be mapped onto#
            - 8000:6379
        restart: always        <--- restart policy for a service "redis-server"

There are four types of restart policy options available for us to use in a docker environment:

  1. No
  2. Always
  3. On-Failure
  4. Unless-Stopped

No: The default restart policy for any docker image, where the container shall not restart when encountered with a situation to close. This can include a runtime issue or a manual intervention such as a SIGTERM or SIGKILL issued by a docker stop or docker kill commands.

Always: Forces the docker container to always restart itself with a new container whenever stopped or killed. Applies for both runtime issues as well as manual interventions. Mostly used with containers which can't be afforded to stop even for a while; such as data services or real-time processes, where even a minute of downtime can cost heavily.

On-Failure: Specifies the docker container to restart when the running application encounters some error and exits with an abnormal exit code. In general, every process returns an error code whenever it is to be terminated. These exit codes can range from 0 to 255 with each value indicating a reason for their termination.

The exit code 0 denotes a process is terminated after completing its task successfully (such as a HTTP calls or Mail for example) while number 1-255 denote a specific error. When used, the container is always restarted when the application terminates with an error code which is not 0.

Unless-Stopped: Specifies the docker container to restart in any circumstances of termination (an execution complete or a failure) unless the container is terminated by a SIGTERM or SIGKILL. Whenever the commands docker stop or docker kill are issued, internally the runtime issues a SIGTERM (normal exit) or SIGKILL (abrupt kill) to the main process in the container. This leads to the process terminating with some exit code (not necessarily a 0). In such scenarios, this policy specifies not to take the exit codes into consideration but just stop.

Join the Newsletter

Subscribe to get our latest content by email.
    We won't send you spam. Unsubscribe at any time.
    We use cookies to provide you with a great user experience, analyze traffic and serve targeted promotions.   Learn More   Accept