Deep Dive into Docker Restart Policies: From ENTRYPOINT Semantics to Container Lifecycle Management

Core Mechanisms of Docker Restart Policies

The --restart flag in Docker allows users to configure restart policies for containers, controlling automatic restart behavior upon container exit. When using --restart=always, the Docker daemon attempts to restart the container indefinitely, regardless of its exit status. This policy plays a crucial role in container management automation, but several semantic details require clarification in practical applications.

ENTRYPOINT Execution Semantics During Restarts

By extending official images and adding custom entrypoint scripts for debugging, the actual behavior of ENTRYPOINT during restart processes can be observed. Experiments show that when a container restarts due to a restart policy, Docker invokes ENTRYPOINT with the original arguments. This indicates that the restart process is essentially a new container instance launch rather than a "resume" of the existing container.

FROM officialImage:version

ENV envOne=value1  \
    envTwo=value2
COPY wrapper-entrypoint.sh /
ENTRYPOINT ["/wrapper-entrypoint.sh"]

Enabling debug mode in the custom wrapper-entrypoint.sh script:

#!/bin/bash
set -x

echo "Be pedantic: all args passed: $@"
bash -x ./original-entrypoint.sh "$@"

Debug output reveals that some official image ENTRYPOINT scripts detect that the container has already been initialized, leading to different behavioral paths. This detection mechanism can cause developers to misunderstand restart semantics, as container state may influence ENTRYPOINT execution logic.

Differential Impact of docker kill vs kill -9

A critical experimental finding shows that when using exec to enter a container and terminating the process with kill -9, a container configured with --restart=always restarts as expected. However, when stopping the container using the docker kill command, the restart policy does not take effect.

This behavioral difference stems from Docker's handling of container stop signals. docker kill sends a SIGKILL signal, and the Docker daemon treats this manual stop as explicit intervention, thus ignoring the restart policy. In contrast, abnormal termination of internal container processes (such as via kill -9) is considered an unexpected exit, triggering the execution of restart policies.

Interaction Between Restart Policies and Data Persistence

The interaction between shared data containers, named volumes, and restart policies is relatively straightforward: data volume lifecycles are independent of container instances. When a container restarts due to a restart policy, mounted data volumes remain unchanged, and the new container instance can access the same persisted data.

However, it's important to note that ENTRYPOINT scripts may exhibit different initialization behaviors based on the current state of data volumes. For example, if a script detects that a data directory already exists, it might skip certain initialization steps, potentially leading to different container behavior after restart compared to initial startup.

Practical Considerations for Restart Policies

Docker provides multiple restart policy options:

• no: Do not automatically restart the container (default)
• on-failure: Restart only if the container exits due to an error (non-zero exit code)
• always: Always restart the container unless manually stopped
• unless-stopped: Similar to always, but after manual container stop, it won't restart even if the Docker daemon restarts

Restart policies only apply after a container successfully starts. Docker requires containers to run for at least 10 seconds before beginning to monitor their restart status, a mechanism that prevents containers that cannot start from entering infinite restart loops.

For already running containers, the docker update command can modify restart policies:

$ docker update --restart unless-stopped redis

Debugging and Monitoring Recommendations

To deeply understand container restart behavior, consider:

1. Using the docker events command to monitor container lifecycle events
2. Checking container status via docker ps (showing as Up or Restarting)
3. Adding debug output to complex ENTRYPOINT scripts, such as enabling bash debug mode with set -x
4. Analyzing log output before and after container restarts using docker logs

Understanding these details helps design containerized applications more effectively, ensuring services recover as expected during failures while avoiding unnecessary restart loops or data consistency issues.