How To Save a Docker Container State

1. Introduction

Docker containers run lightweight applications in isolated environments by design. However, this isolation comes at the cost of persistence. When we stop or remove a container, we lose its file system and any data stored inside. Thus, containers are designed to be ephemeral.

Nevertheless, there are cases where we need to save the state of a running container. This can be to preserve data or replicate an environment quickly. In this article, we’ll explore how to save the state of a Docker container by creating images and exporting.

2. Commit: Saving Container State as an Image

Docker allows us to create an image from a running container using the docker commit command. This becomes useful if we’ve made changes inside the container, such as installing packages or modifying configurations.

2.1. The Command

The syntax of the command is:

docker commit <container_id_or_name> <image_name>:<tag>

Where <container_id_or_name> is the ID or name of the running container, <image_name> is the new name of the image, and <tag> is optional. The generated image is the base image with an additional layer that contains the current state of the container.

It’s important to note that the docker commit command doesn’t capture everything. For example, the image won’t include any mounted volumes set up using the -v or –mount options. This means that files stored in those volumes aren’t part of the new image. Additionally, it doesn’t save container-specific settings such as network configurations, IP addresses, CPU and memory limits, restart policies, or the working directory.

2.2. Example

Let’s look at a practical example of how to save using commit.
We’ll start by running a container from the Ubuntu image:

$ docker run -it ubuntu /bin/bash

In this step, we must apply all the necessary modifications. In this case, inside the running container, we’ll only install the cURL package:

# apt-get update && apt-get install -y curl

Once we’ve finished making changes, let’s save the current state of the container by creating a new image called ubuntu-with-curl:

$ docker commit 81f7bdcc6eff ubuntu-with-curl
sha256:52217d19f1b958a8a2f52f98644d187340cc363db0e22f499ac2469a68a5d78a

The hash value returned is the ID of our newly created image, showing that the operation was successful. To confirm the changes made, we can build a new container with the generated image and check the version of cURL:

$ docker run -it ubuntu-with-curl /bin/bash
# curl --version
curl 8.5.0 (x86_64-pc-linux-gnu) libcurl/8.5.0 OpenSSL/3.0.13 zlib/1.3 brotli/1.1.0 zstd/1.5.5 libidn2/2.3.7 libpsl/0.21.2 (+libidn2/2.3.7) libssh/0.10.6/openssl/zlib nghttp2/1.59.0 librtmp/2.3 OpenLDAP/2.6.7
Release-Date: 2023-12-06, security patched: 8.5.0-2ubuntu10.4
Protocols: dict file ftp ftps gopher gophers http https imap imaps ldap ldaps mqtt pop3 pop3s rtmp rtsp scp sftp smb smbs smtp smtps telnet tftp
Features: alt-svc AsynchDNS brotli GSS-API HSTS HTTP2 HTTPS-proxy IDN IPv6 Kerberos Largefile libz NTLM PSL SPNEGO SSL threadsafe TLS-SRP UnixSockets zstd

To facilitate the distribution of the image, we can use the docker push command to upload it to a remote registry, such as Docker Hub.

3. Docker Export: Saving the Container as a tar File

Sometimes, we might want to export the entire filesystem of a container instead of creating a new image. For this, Docker provides the docker export command, which saves the current state of the container’s filesystem as a tar archive, including files, directories, installed packages, and more.

3.1. The Command

Here’s how we can use docker export:

docker export <container_id> > <filename>.tar

Essentially, it provides a snapshot of the filesystem without the extra details we’ve added, which are required to recreate fully the container in its original state. Thus, the docker export command doesn’t include Docker-specific metadata such as the container’s image layers or environment variables.

Just like when we use docker commit, docker export doesn’t include any files stored on volumes that are connected to the container. So, if we’ve mounted a volume to a folder inside our container, the docker export command will only capture the original contents of that folder, before the volume was connected. The files on the volume itself won’t be saved.

3.2. Example

So, using the same ID as the container we set up in the previous section, let’s now export it to a tar file:

$ docker export 81f7bdcc6eff > ubuntu-with-curl.tar

If we ever need to re-import this filesystem into Docker, we can use the docker import command:

$ docker import ubuntu-with-curl.tar ubuntu-with-curl
sha256:41db1e00c5add5a28c50d7c16728baa7f2088dd4a087e484852f7bb3110e0cd4

This command reads the tar file and creates a filesystem image named ubuntu-with-curl from it.

4. Conclusion

In this article, we studied two docker commands that can save the state of a container: commit and export.

The docker commit command helps create a new image from changes made to a container, such as installing new packages. Alternatively, the docker export command generates a simple tar of the container’s file system without specific details, such as the container’s image layers and metadata.