Run Docker commands
On This Page
- Introduction
- Specifications
- x86 architecture
- Arm architecture
- Docker executor to Remote Docker (Linux/Arm Machine) mapping
- x86 architecture
- Arm architecture
- CircleCI server
- Run Docker commands using the Docker executor
- Install the Docker CLI
- Specify a Docker version for remote Docker
- Run Docker commands using the machine executor
- See also
Use the remote Docker environment to build Docker images within the Docker execution environment.
When you use remote Docker for a job, all Docker commands execute locally on the virtual machine used to spin up your primary Docker container.
| The remote in "remote Docker" is a legacy term from when remote Docker usage would spin up a separate, remote environment for running Docker commands. |
Introduction
To build Docker images (for example, using docker or docker compose commands) when using the Docker execution environment, you must use the setup_remote_docker key in your job:
| Using Docker? Authenticating Docker pulls from image registries is recommended when using the Docker execution environment. Authenticated pulls allow access to private Docker images, and may also grant higher rate limits, depending on your registry provider. For further information see Using Docker authenticated pulls. |
jobs:
build:
docker:
- image: cimg/base:2022.06
steps:
# ... steps for building/testing app ...
- setup_remote_dockerUsing setup_remote_docker for a job means that all Docker commands execute locally on the same virtual machine that used to spin up the primary container.
In the CircleCI web app, jobs that run in the remote Docker environment have the Remote Docker label, as follows:
Only use setup_remote_docker key for jobs where your primary executor is a Docker container. If your job uses a VM rather than a container (for example, your executor is machine) you do not need to use the setup_remote_docker key. For an example, see Run Docker commands using the machine executor. |
Specifications
CircleCI runs remote Docker environments using Linux or Arm machine resource classes, depending on the resource class you assign to the Docker executor.
x86 architecture
A remote Docker environment uses a Linux VM machine resource class that corresponds to the Docker executor class with the following exceptions:
-
smallmaps tomedium(Linux VM) -
medium+maps tolarge(Linux VM)
Arm architecture
Arm-based Docker jobs use an equivalent Arm machine resource class for remote Docker.
Docker executor to Remote Docker (Linux/Arm Machine) mapping
x86 architecture
| Docker resource class | Remote Docker (Linux Machine) resource class |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Arm architecture
| Docker resource class | Remote Docker (Arm Linux Machine) resource class |
|---|---|
|
|
|
|
|
|
|
|
-
Full list of resource classes: Configuration Reference.
-
Full specifications and pricing: CircleCI Pricing
CircleCI server
For CircleCI server installations, contact the systems administrator for specifications.
Run Docker commands using the Docker executor
The example below shows how you can build and deploy a Docker image for our demo Docker project using the Docker executor, with remote Docker:
version: 2.1
jobs:
build:
docker:
- image: cimg/go:1.17
resource_class: xlarge
steps:
- checkout
# ... steps for building/testing app ...
- setup_remote_docker:
docker_layer_caching: true
# build and push Docker image
- run: |
TAG=0.1.$CIRCLE_BUILD_NUM
docker build -t CircleCI-Public/circleci-demo-docker:$TAG .
echo $DOCKER_PASS | docker login -u $DOCKER_USER --password-stdin
docker push CircleCI-Public/circleci-demo-docker:$TAGBelow is a break down of what is happening during this build’s execution:
-
All commands execute in the primary-container. (line 5)
-
Once you call
setup_remote_docker, all Docker-related commands execute locally. (line 12) -
Enable Docker Layer Caching (DLC) to speed up image building. (line 13)
-
We use project environment variables to store credentials for Docker Hub. (line 19)
Install the Docker CLI
CircleCI convenience images have the Docker CLI pre-installed. If you are using a third-party image for your primary container that does not have the Docker CLI installed, then you will need to install it as part of your job before calling any docker commands.
# Install via apk on alpine based images
- run:
name: Install Docker client
command: apk add docker-cliSpecify a Docker version for remote Docker
To optionally specify a Docker version, you can set it as a version attribute with supported tags:
- setup_remote_docker:
version: edgeCircleCI supports the tags listed below for remote Docker, as per our Remote Docker tagging policy.
For x86 and Arm architecture, the following tags are available:
-
default -
edge -
previous
The above tags resolve to the latest supported Docker version, which is Docker 24.
To use Docker 23, the previous Docker release, use the following tag:
-
docker23
To use Docker 24, patch updates will occur until Docker 25 is released, use the following tag:
-
docker24
To use the current deprecated version, Docker 20, use 20.10.24
The version key is not supported on CircleCI server. Contact your system administrator for information about the Docker version installed in your remote Docker environment. |
Run Docker commands using the machine executor
The example below shows how you can build a Docker image using the machine executor with the default image. Note that this does not require the use of remote Docker:
version: 2.1
jobs:
build:
machine:
image: ubuntu-2204:2022.04.2
steps:
- checkout
# start proprietary DB using private Docker image
# with credentials stored in the UI
- run: |
echo "$DOCKER_PASS" | docker login --username $DOCKER_USER --password-stdin
docker run -d --name db company/proprietary-db:1.2.3
# build the application image
- run: docker build -t company/app:$CIRCLE_BRANCH .
# deploy the image
- run: docker push company/app:$CIRCLE_BRANCH