CircleCI 2.0 implemented build support using Docker executors. Upon releasing it, we quickly realized that one of the biggest barriers that CircleCI users encountered was a lack of experience with Docker. In this post, we will discuss Docker and some of the basic commands users should become familiar with.

What is Docker?

Here is a simplified definition of Docker:

“Docker is a platform for developers and sysadmins to develop, deploy, and run applications using containers.”

Docker is also referred to as an application packaging tool that enables applications to be configured and packaged into a Docker image that can be used to spawn Docker containers that run instances of the application. It provides many benefits including runtime environment isolation, consistency via code, and portability. Docker containers can run on any operating system that supports the Docker Engine. To our benefit, most operating systems do support it.

The Docker executor

The CircleCI platform uses a concept called Executors. Executors are environments where your CI/CD jobs/configs are run within the CircleCI platform. CircleCI currently supports three different Executor types:

In this blog post, we will be discussing the Docker executor.

Configuring a Docker executor

CircleCI jobs are defined within a config.yml build configuration file. This is where you specify the usage of a Docker executor for your build. Below is an excerpt from a config.yml file showing an executor definition:

version: 2
      - image: circleci/python:2.7.14

The docker: key directs the platform to build on a Docker executor and the - image: key specifies which Docker image to use when spawning the Docker container. The build will be executed inside a Docker container based on the circleci/python:2.7.14 image.

Basic Docker commands

In response to the issue of user inexperience, we’ve compiled a list of basic Docker commands and links to more information. These will help you understand Docker and control the executor. These commands can be run locally on any computer that has the Docker engine installed.

Building Docker images

Docker containers

Docker image deployments

Additionally, it is important to understand the concept of a Dockerfile: a text document that contains all the commands a user could call on the command line to assemble an image.

The commands listed above are a small subset of the total Docker commands available to users via the Docker engine. They represent a set of relevant commands that will quickly familiarize users with Docker. You can learn more about all the Docker commands here.

Building Docker images on CircleCI

CircleCI has a very cool feature that enables users to easily build Docker images within their CI/CD pipelines. The setup_remote_docker: key is a feature that enables building, running and pushing images to Docker registries from within a Docker executor job. When docker_layer_caching is set to true, CircleCI will try to reuse any Docker images (layers) built during a previous job or workflow that were unchanged. That is, every unchanged layer that was built in a previous job will be accessible in the remote environment. However, there are cases where your job will run in a clean environment, even if the configuration specifies docker_layer_caching: true. These cases involve running many parallel jobs for the same project that depend on the same environment. For more information about Docker Layer Caching, check out the documentation page.


In this post, we have discussed the CircleCI Docker executor and some of the “must know” Docker commands. Familiarizing yourself with these basic commands will remove one of the larger barriers that new users of CircleCI encounter.

If you want to learn more about CircleCI check out the documentation site and if you really get stuck you can also reach out to the CircleCI community via the community/forum site.