Specifying Container Images
This document describes images and containers in the following sections:
- Docker Image Overview
- Using Multiple Docker Images
- Docker and Machine Comparison
- Docker Benefits and Limitations
- Docker Image Best Practices
- Machine Executor Overview
Docker Image Overview
This version of CircleCI enables you to use Docker Images optimized for your needs. This increases performance by building only what is required for your application. Specify a Docker image in your
.circleci/config.yml file that will generate the primary container where all steps run:
jobs: build: docker: - image: buildpack-deps:trusty
In this example, all steps run in the container created by the first image listed under the
build job. To make the transition easy, CircleCI maintains convenience images on Docker Hub for popular languages. See Using Pre-Built CircleCI Docker Images for the complete list of names and tags. If you need a Docker image that installs Docker and has Git, consider using
docker:17.05.0-ce-git, which is an offical Docker image.
Using Multiple Docker Images
It is possible to specify multiple images for your job. Specify multiple images if, for example, you need to use a database for your tests or for some other required service. In a multi-image configuration job, all steps are executed in the container created by the first image listed. All containers run in a common network and every exposed port will be available on
localhost from a primary container.
jobs: build: docker: # Primary container image where all steps run. - image: buildpack-deps:trusty # Secondary container image on common network. - image: mongo:2.6.8 command: [mongod, --smallfiles] working_directory: ~/ steps: # command will execute in trusty container # and can access mongo on localhost - run: sleep 5 && nc -vz localhost 27017
Docker Images may be specified in three ways, by the image name and version tag on Docker Hub or by using the URL to an image in a registry:
Public Convenience Images on Docker Hub
Public Images on Docker Hub
Public Docker Registries
Nearly all of the public images on Docker Hub and Docker Registry are supported by default when you specify the
docker: key in your
config.yml file. If you want to work with private images/registries, please refer to Using Private Images.
Docker and Machine Comparison
docker key defines Docker as the underlying technology to run your jobs using Docker Containers. Containers are an instance of the Docker Image you specify and the first image listed in your configuration is the primary container image in which all steps run. CircleCI also provides a
Like any set of choices, there are tradeoffs to using one over the other. Here’s a basic comparison:
|Start time||Instant||30-60 sec|
|Build Docker images||Yes (1)||Yes|
|Full control over job environment||No||Yes|
(1) Requires using Remote Docker.
Docker Benefits and Limitations
Docker also has built-in image caching and enables you to build, run, and publish Docker images via Remote Docker. Consider the requirements of your application as well. If the following are true for your application, Docker may be the right choice:
- Your application is self-sufficient
- Your application requires additional services to be tested
- Your application is distributed as a Docker Image (requires using Remote Docker)
- You want to use
docker-compose(requires using Remote Docker)
Choosing Docker limits your runs to what is possible from within a Docker container (including our Remote Docker feature). For instance, if you require low-level access to the network or need to mount external volumes check out the
machine executor below.
Docker Image Best Practices
Avoid using mutable tags like
1as the image version in your
config.yml file. Mutable tags often lead to unexpected changes in your job environment. CircleCI cannot guarantee that mutable tags will return an up-to-date version of an image. You could specify
alpine:latestand actually get a stale cache from a month ago. Instead, we recommend using precise image versions or digests, like
redis@sha256:95f0c9434f37db0a4f...as shown in the examples.
If you experience increases in your run times due to installing additional tools during execution, it is best practice to use the Building Custom Docker Images Documentation to create a custom image with tools that are pre-loaded in the container to meet the job requirements.
More details on the Docker Executor are available here.
Machine Executor Overview
Potential Premium Feature Notice: Machine Executor may be available for additional fees in a future pricing update. We welcome your feedback on this and all other aspects of CircleCI 2.0.
When you choose the
machine key, your job will run in a dedicated, ephemeral Virtual Machine (VM). To use the machine executor, simply set the
machine key to
jobs: build: machine: true
circleci/classic:latestis the default image. Changes to this will be announced at least one week before they go live.
circleci/classic:edgereceives the latest updates and will be upgraded at short notice.
circleci/classic:[year-month]Specify an image version from the list of available images. This lets you pin the image version to prevent breaking changes.
The images have common language tools preinstalled. Refer to the specification script for the VM for more information about additional tools.
When To Use the Machine Executor?
- Your application requires full access to OS resources.
- Gives full control over job environment.
- Takes additional time to create VM.
- Only the default image is supported; your job may require additional provisioning.