Docker Stop Command |A Complete Tutorial:Defnition,Syntax,Examples

In the field of Docker container management, the docker stop command serves as a critical tool for mainly shut-down containers. This article talks about the working of the docker stop command, explaining its purpose, usage, and importance of proper container termination.

Docker Container Stop

The primary function of `docker stop` is to stop the execution of a running container. When we run this command shut down, it sends a default SIGTERM signal to the main process within the container, allowing it to perform cleanup operations before terminating the container.

Description

The main process behind the docker container stop goes as, Firstly it sends SIGTERM signal inside the docker container, and after certain short intervals known as grace period, SIGKILL signal command shut will be sent. The first signal SIGTERM acts as warming to the grace period (default 10 secondsthe) it will forcibly seconds shut down, the container.

Basic Syntax

docker stop [OPTIONS] [CONTAINER...]

• `OPTIONS` : provides additional settings for the stop operation of the Docker container.
• `CONTAINER`: The ID or name of the container is to be specified to stop the specific container.

Key Options Of Docker Stop

The following are the key options of Docker Stop Command:

Example

• The following is an example of docker stop command:

docker stop my_container

Checking The Docker Service Status

Before trying the docker commands ensure that the docker software is set up and the service is active. Check the status of the docker service with the command `systemctl status docker`. If the status is active then the docker service is ready to use and then you are good to perform the container operations and management. To check the status of the docker service use the following command:

 systemctl status docker

• You can see in the below figure how to run and check the above command for checking the status of docker.

How "Docker Stop" Terminates A Container?

When you use a `docker stop` as a docker command, Docker initiates a immediate shutdown process. The container receives the SIGTERM signal, allowing its main process to perform the cleanup tasks, such as saving state or closing connections. If the container doesn't respond to the SIGTERM signal within a specified timeout (default is 10 seconds), Docker sends a SIGKILL signal, forcefully terminating the container.

docker stop <container_name or Id>

Options For Customizing The Docker Stop Command

1. `-t` or `--time`: It sets a custom timeout period for the docker container to respond to the SIGTERM signal before forcefully stopping it. In this example the docker container with my_containername wait for the 30seconds after sending the SIGTERM signal then it will go for forcefully termination if it is not responded in that 30seconds.

 docker stop -t 30 my_container

2. `--time=0`: In this, the docker skip the graceful shutdown period and makes immediately send a SIGKILL signal to kill the docker container.

docker stop --time=0 my_container

How To Start A Docker Container

For starting a docker container we use docker start command, but in general we go with docker run command which helps in both starting a container and running a container. Here We are the providing an example of start and running a docker container with ubuntu docker image. The command looks as follows:

docker run -it --name mycontainer1 ubuntu:latest /bin/bash

• The following screenshot illustrates clearly of creating and running the docker container with interactive mode.

• To know more about Docker Run Command, Refer this - Docker Run Command

How To Stop A Running Docker Container

In this below figure you can see the containers that are running through `docker ps` command , are get stopped once we run the command of `docker stop container_name/container_id` . In the status section of the docker ps , we can see that earlier the container is running from 16minutes and once we run the docker stop command the containers get termination its been 8 seconds from that moment. To know more about docker commands refer to the Docker-Cheat Sheet.

How To Stop One Docker Container At A Time

Follow the below steps to stop one Docker running container at a time.

Step 1: Start The Docker Service

• Open your command line containing the Docker software and start The Docker Service with following command:

systemctl enable docker --now

Step 2: Run A Docker Container

• Start The Container using docker run, for example take this as a command:

docker run -dit --name mycontainer centos:latest

Step 3: List The Running Containers

• Run the following command to view the running containers:

docker ps

• To know and view all the containers either they are running or get terminated specify the above command with option -a , the command looks as given below:

docker ps -a

Step 4: Stop The Docker Container

• If multiple containers are running then the specific container name or ID that you are looking to stop. In this case I want to stop the container with name mycontainer.

docker stop mycontainer

• In this, the docker container with name my_container is get stopped from the execution, by sending the SIGTERM signal to backend through the option stop and finally the my_container leads to the graceful termination. This below shows you that clearly.

Step 5: Stop The Docker Container With Time Period ( Optional )

• You can also stop a running docker container with a grace period of 30 seconds and exits.

docker stop --time=30 myc1

How To Stop Docker Container By ID

In this we specified the docker container ID instead of docker container name for stoping from the execution and making the container with id 'd3ca5e7b6f8b' for graceful termination. while specifying the container id we have to make ensure it is unique with id from other , we don't need to specify all the characters of the container id.

docker stop d3ca5e7b6f8

How "docker stop" Works?

When you execute a docker stop command along with the container name or id, the docker on behind sends two single signals to the container before the termination. The first signal known as SIGTERM signal warns the container for possible termination after the default grace time of 10seconds it sends another signal known as SIGKILL signal that terminates the running container. The Flow of docker stop explain in steps as follows:

Step 1: Initiating Stop process by running command as follows:

docker stop <container_name or container_id>

Step 2: Docker sends SIGTERM signal to container.

Step 3: Graceful Shutdown (If possible): When the container receives the SIGTERM signal the main process of container starts cleaning of necessary tasks and closing connections.

Step 4: Timeout Period, By default timeout period 10seconds are provided, or else you can customize and set our time for the main process to clean the tasks.

Step 5: Send SIGKILL Signal (If Necessary), If the container is not able to respond with termination of the container within the specified time, docker sends SIGKILL signal to the container immediately.

How "docker kill" Works?

Docker kill command sends only one signal known as SIGKILL signal that terminate the running container, it doesn't provide any grace time for the container's main process to clean the tasks, close the connections. That the reason, this docker kill command takes lesser time compared to docker stop command. It is only recommended to use docker kill in necessary cases. It preferred to not to use it in generally.

How To Force Stop/ Kill A Docker Container?

The force stopping of a docker container is the known killing a container, The above section explained how the docker kill command works. It directly sends a SIGKILL signal to the Container. The following steps helps in killing the docker container.

Step 1: List the docker containers and chose the running container you want to force stop. The following command help in listing the running containers.

docker ps

Step 2: Now run the following command to force stop the container that you want to kill. Here I want to force stop the myc1 named running container.

docker kill myc1

Step 3: Verify the step2 by listing the containers with the following command:

docker ps

How To Stop All Running Docker Containers

The following steps guide you in stopping all the running docker containers at once:

Step 1: Start The Stopped/Paused Containers

• Firstly ensure to have many running containers to understand this concept effectively.
• Begin all the paused containers to running state and try on creating new containers if interested. Use the following command to start all the paused containers at once.

docker start $(docker ps -a -q)

Step 2: Listing All The Docker Containers

• Check all the containers' status once by running the following command:

docker ps -a

Step 3: Stop All The Docker Containers

• Now Stop the all the running containers with the following command;

docker stop $(docker ps -aq)

( or )

• You can also stop the execution simultaneously through one command by specifying their names or IDs one by one with space separation.

docker stop container1 container2

Step 4: Verify Listing The Running Containers

• As a verification, you can use the following command "docker ps". It displays empty that means all the running containers are successfully stopped.

How To Delete/Remove A Docker Container

In Docker, Containers can be deleted using rm option similar to for stopping we use stop command. The following are the steps guiding how to delete a docker container.

Step 1: Firstly stop the container that you intended to delete using the steps discussed above section. Its is necessarily recommended to stop the running container before deleting them.

• If you tried deleting a running container without stopping it first, It raises the error while deleting it. The command to stop the container is as follows:

docker stop myc1

• Here We are stopping the container named with mycontainer1.

Step 2: Remove A Container By Name

• Now Use the following command to delete that stop container named mycontainer1:

docker rm myc1

• In this screenshot you can see that after execution of above command, it prints the deleted container name.

Step 3: Listing All The Docker Containers

• Verify the containers by listing all to see whether that container is deleted or not. Use the following command to verify:

docker ps -a

• This below screenshots shown after deletion of the container "myc1" it is removed from the list of containers successfully.

How To Remove/Delete All The Docker Containers

The following steps guide you how to delete all the docker containers:

Note: Ensure to have many containers available in running state to understand this concept clearly.

Step 1: Stop The all the running docker containers with this command:

docker stop `docker ps -q`

(or)

docker stop $(docker ps -aq)

Step 2: Use the following command to delete all the containers:

docker rm `docker ps -aq`

(or)

docker rm $(docker ps -aq)

• The following screenshot illustrates clearly about the removing all the containers and printing removed container ids.

Step 3: Verify whether all containers are removed successfully or not with the following command:

docker ps -aq

• This below makes you clear that all the containers are successfully deleted at once. There are no containers available to list out.

How To List All The Running Docker Containers

Docker container can be listed using docker ps command. The following command list all the docker containers with running state.

docker ps 

• This below screenshot makes you understand that all the running containers are listed and can see when do they have started.

How To List All The Docker Containers

The following command is used to list all the containers either it is running or in stopped state.

docker ps -a

• The below screenshot makes clear understanding for you with seeing the outputs of both commands. That `docker ps` list out only the running containers whereas `docker ps -a list ` out all the containers.

How To Stop And Remove Containers In Docker Compose

In Docker Compose, you can stop and remove the containers that are associated with your Docker compose project file on using the docker-compose down command. Lets following the implementation stepswise.

Step 1: Create A Docker Compose Yaml File

• Firstly Created a docker-compose.yaml file with the following code.

version: '3.8'

services:
  centos1:
    container_name: mycontainer1
    image: centos:latest

  centos2:
    container_name: mycontainer2
    image: centos:latest

Step 2: Start The Docker Compose Containers

• Now, start the containers specified docker-compose yaml file with the following command:

docker-compose up

Step 3: Stop And Remove The Docker Compose Containers

• Finally Stop the docker containers that are associated with docker compose with the following command:

docker-compose down

Examples of Docker Stop Command with Options

The following are the examples of Docker stop command with options:

1. Stop a Single Container

• The following is used to stop a single container:

docker stop <container_id_or_name>

2. Stop a Container with a Custom Timeout

• The following command is used to stop a container with a custom Timeout:

docker stop -t 30 <container_id_or_name>

3. Stop Multiple Containers

• The following command is used to stop multiple containers:

docker stop <container_id_or_name1> <container_id_or_name2>

4. Stop All Running Containers

• The following command is used to stop all the running containers:

docker stop $(docker ps -q)

Docker Container Stop Vs Kill

Both the commands docker container stop and docker container kill are used for terminating the containers only. But docker container stop will terminated the contianer by genrating 2 signals, firstly it sends warning singal regarding terminal, giving time (grace period) for the container to clear the resources properly and then after grace time it is terminated by docker stop forcely.

Whereas Docker container kill sends only one signal (SIGKILL) it directly shutdown the container, without giving any time for the container to clear the resources properly. That's the reason docker kill command shutdowns the container very fast compared to docker stop. But docker kill command in only recommand to use, when the docker stop taking more time to terminated it, and it is less sensitive container application.

Common Issues and troubleshooting Regarding Docker Stop

The following are the some of the common issues and troubleshooting tips regarding docker stop command:

• Container Not Stopping: Try to use the docker kill with the container name to forcefully stop the container when they is a need.
• Timeout Too Short: Try to increase the timeout period of the container with docker stop -t <seconds> <container_id_or_name> to give more graceful period of time for stopping the processes.
• Unresponsive Docker Daemon: Try to restart the Docker daemon using sudo systemctl restart docker, when they are some changes or configuration that has to updated or loaded.
• Permission Denied: Run the command with sudo or add your user to the docker group, if you are getting permissions denied error while excuting the command.

Use Cases of Docker Stop Command

The following are the use cases of docker stop command:

• Graceful Shutdown: The docker stop command is useful for safely stopping the container allowing all the processes inside the container terminate properly.
• Maintenance and Updates: Try to halt the containers for system maintenance or software updates.
• Resource management: Try to free up the system resources by stopping the unused or idle containers.
• Environment Reset: It is helpful for stopping and restarting the containers to refresh the development or testing environments.

People also Read

Conclusion

In conclusion, the `docker stop` command plays a crucial role in the controlling the termination of Docker containers. It allows containers to handle shutdown signals and ensures that applications have an opportunity to clean up resources before coming to a halt. Whether you're managing a single container or orchestrating complex applications, understanding and utilizing `docker stop` is essential for maintaining a well-organized and efficient Docker environment.