Stopping and Restarting Docker Containers: Essential Commands and Best Practices

Stopping and Restarting Containers in Docker: A Complete Guide

In Docker, containers are isolated environments that run applications or services. Sometimes, you need to stop a container (for maintenance, updates, or to free resources), and later restart it. This guide provides an in-depth look at how to stop and restart Docker containers effectively.

---

1. Stopping Docker Containers

When a container is running, you can stop it using the docker stop command. Stopping a container means that the container will be gracefully shut down, and the resources it consumes will be released.

a. Stopping a Single Container

To stop a running container, use the docker stop command followed by the container's name or ID:

docker stop container_name_or_id

Example:

docker stop my_nginx

This command will stop the container named my_nginx.

b. Stopping Multiple Containers

You can stop multiple containers at once by specifying their names or IDs, separated by a space:

docker stop container1 container2 container3

Example:

docker stop web_container db_container

c. Graceful Shutdown vs Forceful Stop

By default, Docker tries to gracefully stop a container by sending a SIGTERM signal, which allows processes inside the container to shut down properly. If the container does not stop within the specified timeout (10 seconds by default), Docker sends a SIGKILL signal to forcefully stop the container.

• You can change the timeout with the -t option:

  docker stop -t 30 container_name

This command gives the container 30 seconds to gracefully shut down before forcefully stopping it.

---

2. Restarting Docker Containers

Sometimes you might need to restart a container, either to apply changes or recover from an issue. Docker provides the docker restart command to accomplish this.

a. Restarting a Single Container

To restart a container, simply use the docker restart command followed by the container's name or ID:

docker restart container_name_or_id

Example:

docker restart my_nginx

This will stop and then immediately start the container again.

b. Restarting Multiple Containers

You can restart multiple containers at once by providing their names or IDs separated by a space:

docker restart container1 container2 container3

Example:

docker restart web_container db_container

c. Specifying Timeout for Restart

By default, Docker will wait for 10 seconds for the container to stop gracefully before starting it again. You can specify a custom timeout with the -t option:

docker restart -t 30 container_name

This command will wait for 30 seconds before forcefully restarting the container.

---

3. Restart Policies

Docker allows you to configure restart policies for containers. Restart policies define when a container should be automatically restarted by Docker.

You can set a restart policy at the time of creating the container using the --restart flag.

a. Types of Restart Policies

1. no: The container will not be restarted automatically (default).
2. always: The container will always restart unless explicitly stopped.
3. on-failure: The container will restart only if it exits with a non-zero exit status (indicating failure).
4. unless-stopped: The container will restart unless it is explicitly stopped by the user.

b. Setting a Restart Policy

When creating or running a container, you can specify the restart policy using the --restart option:

docker run --restart always nginx

This command will ensure that the nginx container is restarted automatically if it stops, crashes, or is manually stopped (unless explicitly stopped).

c. Restart Policy Examples

• Always restart unless manually stopped:

  docker run --restart unless-stopped ubuntu

• Restart on failure (with a maximum retry limit):

  docker run --restart on-failure:5 ubuntu

This will restart the container if it exits with a non-zero exit code, but it will only retry a maximum of 5 times.

---

4. Stopping and Restarting Containers Using Docker Compose

Docker Compose simplifies the management of multi-container applications. It allows you to define services in a docker-compose.yml file and manage them collectively.

a. Stopping Containers with Docker Compose

To stop all containers defined in a docker-compose.yml file:

docker-compose down

This command stops and removes the containers, networks, and volumes defined in the Compose file.

To only stop the containers without removing them:

docker-compose stop

b. Restarting Containers with Docker Compose

To restart all containers in a Docker Compose application:

docker-compose restart

To restart a specific service defined in the Compose file:

docker-compose restart service_name

Example:

docker-compose restart web

This will restart only the web service in the Compose file.

---

5. Viewing Container Logs After Restart

After stopping or restarting a container, you might want to check the logs to ensure the application started correctly or troubleshoot any issues. You can use the docker logs command:

docker logs container_name_or_id

Example:

docker logs my_nginx

This will display the logs of the container my_nginx.

---

6. Troubleshooting Stopping and Restarting Containers

Here are some common issues you might encounter when stopping or restarting containers:

a. Container Not Stopping

• If a container does not stop within the expected time, you can force stop it by using docker kill, which immediately sends the SIGKILL signal to the container:

  docker kill container_name

• Investigate the container logs using docker logs to check if any processes inside the container are not shutting down correctly.

b. Container Not Restarting

• Ensure the container has the necessary configuration to restart (i.e., check the restart policy).
• If a container is restarting endlessly, it might be due to misconfiguration or failure in the container’s entry process. Inspect the logs and check the container’s exit status using docker inspect.

c. Restart Policy Not Working

• Restart policies only apply to containers that exit. If a container is stopped manually using docker stop, it will not automatically restart unless the policy is always or unless-stopped.

---

7. Conclusion

Stopping and restarting Docker containers is a fundamental part of container management. With Docker commands like docker stop, docker restart, and restart policies, you have full control over the lifecycle of your containers. Additionally, Docker Compose makes it easier to manage multi-container applications, including stopping and restarting services.

By following best practices for managing containers and using restart policies, you can ensure that your containers are resilient and behave as expected in different scenarios.

---