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

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.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation