CircleCI and Docker: What you need to know

Written by Angel Rivera

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.

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:

• Docker
• Machine
• MacOS

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 
jobs: 
  build: 
    docker: 
      - 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 images lists Docker images found locally
• docker build -t <image name> . creates a Docker image with a tag using -t

Docker containers

• docker ps lists all of the running Docker containers. Use the -a flag to show all of the running and not running containers.
• docker rm <container name> deletes a container or multiple containers
• docker rmi deletes Docker images locally
• docker start <container name> starts an existing container
• docker stop <container name> stops an existing container
• docker run runs a command in a new container
• docker logs fetches a container’s logs

Docker image deployments

• docker login logs into a Docker registry
• docker push pushes an image or a repository to a registry
• docker pull pulls an image or a repository from a registry
• docker logout logs out from a Docker registry

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 https://discuss.circleci.com/ community/forum site.

Originally published at circleci.com by Angel Rivera on September 20, 2018.