How to Use setup_remote_docker in CircleCI

By Kaveh Alemi·Latchkey

The setup_remote_docker step attaches a separate Docker environment to a docker-executor job, giving docker commands a daemon to talk to.

Add setup_remote_docker before any docker build/docker push step. The CLI in your primary container then drives a remote daemon, so you can build images without the machine executor.

Steps

Add - setup_remote_docker as a step (optionally with docker_layer_caching: true).
Run docker build and docker push as normal in later steps.
Authenticate to your registry first so the push is allowed.

Config

.circleci/config.yml

version: 2.1
jobs:
  build-image:
    docker:
      - image: cimg/base:2024.02
    steps:
      - checkout
      - setup_remote_docker:
          docker_layer_caching: true
      - run: echo "$DOCKERHUB_TOKEN" | docker login -u "$DOCKERHUB_USER" --password-stdin
      - run: docker build -t acme/app:$CIRCLE_SHA1 .
      - run: docker push acme/app:$CIRCLE_SHA1
workflows:
  build:
    jobs: [build-image]

Gotchas

Files in your primary container are not directly mounted into the remote daemon; copy what the build needs into the build context.
Docker layer caching is a paid feature; without it every build starts from cold layers.

Verify it actually works

Trigger the real event rather than a manual run. Manual dispatch populates a different context, so behaviour depending on the event will differ.
Assert on the outcome, not on the step exiting zero. Many steps report success while producing nothing.
Check it on a fresh runner with a cold cache once, so you are not testing warm state that will not exist on the next contributor machine.

Frequently asked questions

How do I use setup_remote_docker in CircleCI?

Add setup_remote_docker before any docker build/docker push step. The CLI in your primary container then drives a remote daemon, so you can build images without the machine executor.