How to Edit Files or Restart Docker Daemon in Remote Docker Environment

Overview

Configure Docker registry mirrors in CircleCI's remote Docker environment to protect builds from Docker Hub rate limits and outages. Files can be created or modified on the remote-docker host using SSH commands.

Prerequisites

A CircleCI project using setup_remote_docker
A Docker registry mirror URL (e.g., https://mirror.gcr.io). Note: mirror.gcr.io is Google's Docker pull-through cache and remains available. If you are storing your own images in GCR, note that Google Container Registry is deprecated in favour of Google Artifact Registry.

Instructions

Step 1: Set Up Remote Docker

Add setup_remote_docker to your job configuration:

- setup_remote_docker

Step 2: Create or Edit daemon.json

Use SSH to write the Docker daemon configuration file on the remote-docker host:

- run:
    name: Configure Docker registry mirror
    command: |
      cat << EOF | ssh remote-docker "sudo tee /etc/docker/daemon.json"
      {
        "registry-mirrors": ["https://mirror.gcr.io"]
      }
      EOF

Note: Use tee to create or overwrite the file. Use tee -a to append to an existing file.

Step 3: Reload Docker Daemon

Signal the Docker daemon to reload its configuration without restarting:

ssh remote-docker "sudo pkill -SIGHUP dockerd"
sleep 3

Step 4: Verify Configuration

Confirm the mirror is active:

docker system info

Solution

Complete working example:

version: 2.1

jobs:
  build:
    docker:
      - image: cimg/base:current
    steps:
      - checkout
      - setup_remote_docker
      
      - run:
          name: Configure Docker registry mirror
          command: |
            cat \<< EOF | ssh remote-docker "sudo tee /etc/docker/daemon.json"
            {
              "registry-mirrors": ["https://mirror.gcr.io"]
            }
            EOF
            ssh remote-docker "sudo pkill -SIGHUP dockerd"
            sleep 3
            docker system info

Important Notes

Per-job configuration: This setting applies only to the current remote-docker instance. Add this step to each job requiring the mirror.
Transparent operation: Docker pulls display canonical image names (e.g., docker.io/library/nginx:alpine) even when using the mirror. This is expected behavior.
Automatic fallback: If the mirror becomes unavailable, Docker automatically falls back to Docker Hub.
General strategy: This SSH-based approach can be used to create or edit other configuration files in the remote-docker environment as well.
Debug logging (optional): Add verbose logging for troubleshooting:

  {
    "registry-mirrors": ["https://mirror.gcr.io"],
    "log-level": "debug"
  }

The registry-mirrors setting in Docker only works for Docker Hub (docker.io) images. It does not apply to other registries like registry.dagger.io.

Additional Resources