Restarting containers in Docker - Deep Dive

Overview - Restarting containers

What is it?

Restarting containers means stopping a running container and then starting it again. This process refreshes the container's state and can apply changes or recover from errors. It is a common task in managing containerized applications to ensure they run smoothly.

Why it matters

Containers can sometimes stop working correctly due to errors or resource issues. Restarting them quickly restores their operation without rebuilding or redeploying. Without restarting, problems could persist, causing downtime or degraded service, which affects users and business reliability.

Where it fits

Before learning to restart containers, you should understand what containers are and how to run them using Docker. After mastering restarting, you can explore container orchestration tools like Kubernetes that manage container lifecycles automatically.

Mental Model

Core Idea

Restarting a container is like turning a device off and on again to refresh its state and fix temporary problems.

Think of it like...

Imagine your smartphone freezes or slows down. Restarting it closes all apps and clears temporary glitches, making it work smoothly again. Restarting a container works the same way for software inside it.

┌───────────────┐     stop     ┌───────────────┐
│ Running      │────────────▶│ Stopped       │
│ Container   │             │ Container     │
└───────────────┘             │               │
                             │ start         │
                             ▼               ▼
                         ┌───────────────┐
                         │ Running      │
                         │ Container   │
                         └───────────────┘

Build-Up - 7 Steps

1

Foundation

What is a Docker container

Concept: Introduce the basic idea of a container as a lightweight, isolated environment for running applications.

A Docker container packages an application and its environment so it runs the same everywhere. It is like a small virtual machine but faster and uses fewer resources. Containers start and stop quickly.

Result

You understand what a container is and why it is useful.

Knowing what a container is helps you see why restarting it can fix problems without affecting the whole system.

2

Foundation

Starting and stopping containers

Concept: Learn the basic Docker commands to start and stop containers.

Use 'docker run' to start a new container. Use 'docker stop ' to stop a running container. Stopping means the container pauses and frees resources but still exists on disk.

Result

You can control container lifecycle manually.

Understanding start and stop commands is essential before learning how to restart containers.

3

Intermediate

Restart command basics

Concept: Learn the 'docker restart' command that combines stop and start in one step.

The command 'docker restart ' stops the container if running and then starts it again immediately. This is faster and simpler than running stop and start separately.

Result

You can restart containers quickly with one command.

Knowing the restart command saves time and reduces errors compared to manual stop and start.

4

Intermediate

Restart policies for automatic restarts

🤔Before reading on: do you think containers restart automatically by default? Commit to yes or no.

Concept: Docker can automatically restart containers on failure or system reboot using restart policies.

You can set restart policies like 'always', 'on-failure', or 'unless-stopped' when running a container. For example, 'docker run --restart always' makes Docker restart the container if it crashes or the system reboots.

Result

Containers can recover automatically without manual intervention.

Understanding restart policies helps you build resilient systems that self-heal from crashes.

5

Intermediate

Graceful vs forced restarts

🤔Before reading on: do you think 'docker restart' always waits for the container to stop cleanly? Commit to yes or no.

Concept: Restarting can be graceful (waiting for stop) or forced (killing immediately).

By default, 'docker restart' sends a stop signal and waits 10 seconds before killing the container. You can change this timeout with 'docker restart -t '. This controls how long the container has to clean up before forced stop.

Result

You can control restart behavior to avoid data loss or corruption.

Knowing the difference prevents accidental data loss during restarts.

6

Advanced

Restarting containers with volumes and networks

🤔Before reading on: do you think restarting a container affects its data stored in volumes? Commit to yes or no.

Concept: Restarting a container does not delete its data volumes or network settings.

Volumes are stored outside the container filesystem and persist across restarts. Network settings remain unless the container is removed. Restarting refreshes the container process but keeps data intact.

Result

You can safely restart containers without losing persistent data.

Understanding persistence boundaries helps avoid accidental data loss.

7

Expert

Restart behavior in container orchestration

🤔Before reading on: do you think Kubernetes uses the same restart commands as Docker CLI? Commit to yes or no.

Concept: Orchestration platforms manage container restarts differently with health checks and policies.

Kubernetes uses pod lifecycle management and probes to decide when to restart containers automatically. It does not use 'docker restart' but controls container processes directly. Restart policies in Kubernetes are more complex and integrated with cluster state.

Result

You understand how container restarts scale in production environments.

Knowing orchestration restart mechanisms prepares you for managing containers at scale beyond Docker CLI.

Under the Hood

When you run 'docker restart', Docker sends a SIGTERM signal to the container's main process, allowing it to stop gracefully. If the process does not exit within the timeout, Docker sends SIGKILL to force termination. Then Docker starts the same container again with the same configuration and mounts. The container's filesystem and volumes remain unchanged, so data persists.

Why designed this way?

This design balances graceful shutdown to avoid data corruption with a forced kill fallback to prevent hangs. It reuses the existing container configuration to quickly restart without rebuilding. Alternatives like deleting and recreating containers would be slower and risk data loss.

┌───────────────┐
│ docker restart│
└──────┬────────┘
       │
       ▼
┌───────────────┐   SIGTERM   ┌───────────────┐
│ Container    │───────────▶│ Graceful stop │
│ main process │            └───────────────┘
└──────┬────────┘                 │
       │                          │
       │ Timeout expires          │
       ▼                          ▼
┌───────────────┐   SIGKILL    ┌───────────────┐
│ Container    │───────────▶│ Forced stop   │
│ main process │            └───────────────┘
└──────┬────────┘                 │
       │                          │
       ▼                          ▼
┌───────────────┐           ┌───────────────┐
│ Start new    │◀──────────│ Restart done  │
│ container   │            └───────────────┘
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does 'docker restart' delete container data? Commit yes or no.

Common Belief: Restarting a container deletes all its data and resets it to a fresh state.

Reality: Restarting only stops and starts the container process; data in volumes or container filesystem persists.

Why it matters: Believing data is lost can cause unnecessary backups or fear of restarting, leading to longer downtimes.

Quick: Do containers restart automatically by default? Commit yes or no.

Common Belief: Containers always restart automatically if they crash or the system reboots.

Reality: By default, containers do not restart automatically unless a restart policy is set.

Why it matters: Assuming automatic restart can cause unnoticed downtime if containers stop unexpectedly.

Quick: Does 'docker restart' wait forever for a container to stop? Commit yes or no.

Common Belief: 'docker restart' waits indefinitely for the container to stop gracefully before killing it.

Reality: It waits only a default timeout (10 seconds) before forcing a kill.

Why it matters: Expecting indefinite wait can cause confusion when containers are killed abruptly, risking data loss.

Quick: Is 'docker restart' the same as removing and recreating a container? Commit yes or no.

Common Belief: Restarting a container is the same as deleting and creating a new one.

Reality: Restarting keeps the same container instance and its settings; removing and recreating is a different process.

Why it matters: Confusing these leads to mistakes like losing container state or data unintentionally.

Expert Zone

1

Restart policies interact with container health checks; a container marked unhealthy may be restarted automatically even if running.

2

Restarting a container does not reset environment variables or runtime parameters unless the container is recreated.

3

Docker's restart timeout can be tuned per container, which is critical for applications needing longer shutdown times.

When NOT to use

Restarting is not suitable when you need to update container images or configuration; in those cases, recreate containers with new settings. For complex multi-container apps, use orchestration tools like Kubernetes for controlled rolling restarts.

Production Patterns

In production, restart policies are combined with monitoring to auto-recover from crashes. Graceful shutdown hooks ensure data integrity during restarts. Orchestrators handle restarts based on health probes and resource constraints.

Connections

Operating System Process Management

Restarting containers parallels stopping and starting OS processes.

Understanding how OS signals like SIGTERM and SIGKILL work helps grasp container restart behavior.

Fault Tolerance in Distributed Systems

Restart policies implement fault tolerance by recovering failed components automatically.

Knowing restart mechanisms aids in designing resilient distributed applications that self-heal.

Smartphone Rebooting

Both restart processes refresh state and clear temporary errors.

Recognizing this similarity helps non-technical learners intuitively understand container restarts.

Common Pitfalls

#1 Restarting a container expecting configuration changes to apply without recreating it.

Wrong approach:

docker restart mycontainer

Correct approach:

docker rm -f mycontainer && docker run [options] myimage

Root cause:

Restarting only restarts the existing container instance; changes to image or config require recreating the container.

#2 Assuming containers restart automatically after a crash without setting restart policy.

Wrong approach:

docker run myimage

Correct approach:

docker run --restart unless-stopped myimage

Root cause:

Default Docker behavior does not restart containers automatically; explicit policy is needed.

#3 Using 'docker restart' on a container that needs a long graceful shutdown without adjusting timeout.

Wrong approach:

docker restart mycontainer

Correct approach:

docker restart -t 30 mycontainer

Root cause:

Default 10-second timeout may kill processes prematurely, causing data loss.

Key Takeaways

Restarting containers stops and starts the container process to refresh its state without deleting data.

The 'docker restart' command combines stop and start with a default timeout for graceful shutdown.

Restart policies enable automatic container recovery after crashes or system reboots, improving reliability.

Restarting does not apply configuration or image changes; recreating containers is needed for updates.

Understanding restart behavior is essential for building resilient, maintainable containerized applications.