Start Building for Free
CircleCI.comAcademyBlogCommunitySupport

Run Docker commands

1 week ago3 min read
Cloud
Server v4+
On This Page

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.

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:

jobs:
  build:
    docker:
      - image: cimg/base:2022.06
    steps:
      # ... steps for building/testing app ...
      - setup_remote_docker

Using 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:

Remote Docker label

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:

  • small maps to medium (Linux VM)

  • medium+ maps to large (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 classRemote Docker (Linux Machine) resource class

small

medium (Linux VM)

medium

medium (Linux VM)

medium+

large (Linux VM)

large

large (Linux VM)

xlarge

xlarge (Linux VM)

2xlarge

2xlarge (Linux VM)

Arm architecture

Docker resource classRemote Docker (Arm Linux Machine) resource class

arm.medium

arm.medium (Arm VM)

arm.large

arm.large (Arm VM)

arm.xlarge

arm.xlarge (Arm VM)

arm.2xlarge

arm.2xlarge (Arm VM)

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:$TAG

Below is a break down of what is happening during this build’s execution:

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-cli

Specify 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: edge

CircleCI 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

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

Suggest an edit to this page

Make a contribution
Learn how to contribute