How to use docker container restart command to manage containers

Introduction

In this lab, you will learn how to effectively manage Docker containers using the docker restart command. You will begin by understanding the basic process of restarting a running container, a fundamental operation for applying changes or resolving issues.

Building upon this, you will explore more advanced restart options. This includes specifying a custom timeout for the restart process, allowing you to control how long Docker waits for a container to gracefully stop before forcing termination. Finally, you will learn how to restart a container using a specific signal, providing granular control over the container's shutdown behavior during a restart.

Restart a running container

In this step, you will learn how to restart a running Docker container. Restarting a container is a common operation when you need to apply configuration changes, fix issues, or simply refresh the container's state.

First, let's pull a simple Nginx image to use for our examples. We will use the nginx:latest image.

docker pull nginx:latest

You should see output indicating that the image is being pulled and extracted.

Next, we will run a container based on this image. We will run it in detached mode (-d) so it runs in the background and assign it a name (--name my-nginx).

docker run -d --name my-nginx nginx:latest

This command will start the Nginx container and print its container ID.

To verify that the container is running, you can use the docker ps command.

docker ps

You should see the my-nginx container listed with a status of Up.

Now, let's restart the running container using the docker restart command followed by the container name.

docker restart my-nginx

This command will stop the container and then start it again.

To confirm that the container has been restarted and is running again, use docker ps once more.

docker ps

You should see the my-nginx container listed again, and the STATUS column should show Up with a time indicating it was recently started.

Restart a container with a specific timeout

In this step, you will learn how to restart a Docker container with a specific timeout. When you restart a container, Docker sends a stop signal (by default, SIGTERM) to the main process in the container. If the process doesn't exit within a certain period, Docker sends a kill signal (SIGKILL) to force it to stop. The default timeout is 10 seconds. You can adjust this timeout using the -t or --time flag with the docker restart command.

Let's use the my-nginx container we created in the previous step. First, ensure it is running.

docker ps

If the container is not running, start it again:

docker start my-nginx

Now, we will restart the container with a timeout of 5 seconds. This means Docker will wait for 5 seconds after sending the stop signal before sending the kill signal.

docker restart -t 5 my-nginx

You should see the container name printed, indicating the restart command was executed.

To observe the effect of the timeout, you would typically need a container that takes longer than the default 10 seconds to shut down gracefully. However, for this exercise, we are focusing on the command syntax.

Let's try restarting with a longer timeout, say 20 seconds.

docker restart --time 20 my-nginx

Again, you will see the container name printed.

The -t or --time option is useful when you have applications running in containers that require more time to perform cleanup operations before shutting down.

To confirm the container is still running after the restart, use docker ps.

docker ps

You should see my-nginx listed with a status of Up.

Restart a container with a specific signal

In this step, you will learn how to restart a Docker container by sending a specific signal to the container's main process. While docker restart sends a default stop signal (SIGTERM) followed by a kill signal (SIGKILL) after a timeout, you might need to send a different signal depending on the application running inside the container. You can achieve this by first stopping the container with a specific signal using docker stop and then starting it again with docker start.

Let's use the my-nginx container again. Ensure it is running.

docker ps

If it's not running, start it:

docker start my-nginx

Now, we will stop the container by sending the SIGKILL signal. This signal immediately terminates the process without allowing it to perform any cleanup.

docker stop -s SIGKILL my-nginx

You should see the container name printed, and if you run docker ps, the container should no longer be listed.

docker ps

The container is now stopped. To restart it, we simply start it again.

docker start my-nginx

The container should now be running again. Verify with docker ps.

docker ps

You should see my-nginx listed with a status of Up.

While SIGKILL is a forceful stop, you can send other signals as well, such as SIGHUP or SIGINT, if your application is configured to handle them for graceful shutdowns or reloads. However, the nginx container's default configuration handles SIGTERM gracefully.

Let's stop the container again, this time using the default SIGTERM signal (which is the default for docker stop if no signal is specified).

docker stop my-nginx

Verify that it is stopped:

docker ps

Now, start it one last time.

docker start my-nginx

Verify it is running:

docker ps

By combining docker stop -s <signal> and docker start, you have more granular control over how a container is stopped before being restarted.

Summary

In this lab, you learned the fundamental process of restarting a running Docker container using the docker restart command. You practiced pulling a Docker image, running a container in detached mode, verifying its status, and then successfully restarting it.

Furthermore, you explored how to control the restart process by specifying a timeout period using the -t or --time flag, allowing you to adjust the time Docker waits for a container to gracefully stop before forcefully terminating it.