Running Docker Commands

This document explains how to build Docker images for deployment elsewhere or further testing, and how to start services in a remote docker environment.


To build Docker images for deployment, you must use a specialsetup_remote_docker为每个构建创建一个单独的环境的键。此环境非常远程,完全隔离,并已配置为执行Docker命令。如果您的工作需要dockerorDocker撰写命令,添加setup_remote_docker进入你的。Circleci./config.yml:

jobs:建立:steps:# ... steps for building/testing app ...-setup_remote_docker:version:19.03.13

什么时候setup_remote_dockerexecutes, a remote environment will be created, and your currentprimary containerwill be configured to use it. Then, any docker-related commands you use will be safely executed in this new environment.

Note:The use of thesetup_remote_dockerkey is reserved for configs in which your primary executorisa docker container. If your executor ismachine(and you want to use docker commands in your config) you donotneed to use thesetup_remote_dockerkey.


The Remote Docker Environment has the following technical specifications (for CircleCI Server installations, contact the systems administrator for specifications):

CPU. Processor 内存 HD
2 Intel(R) Xeon(R) @ 2.3GHz 8GB 100GB


The example below shows how you can build a Docker image using themachineexecutor with the default image - this does not require the use of remote Docker:

version:2jobs:建立:machine:truesteps:-checkout# start proprietary DB using private Docker image# with credentials stored in the UI-run:|echo "$DOCKER_PASS" | docker login --username $DOCKER_USER --password-stdindocker 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

The example below shows how you can build and deploy a Docker image for ourdemo docker projectusing the Docker executor, with remote Docker:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
version:2.1jobs:建立:docker:-image:Circleci./golang:1.15auth:username:mydockerhub-userpassword:$ dockerhub_password.# context / project UI env-var referencesteps:-checkout# ... steps for building/testing app ...-setup_remote_docker:version:19.03.13docker_layer_caching:true# build and push Docker image-run:|TAG=0.1.$CIRCLE_BUILD_NUMdocker build -t CircleCI-Public/circleci-demo-docker:$TAG .echo $DOCKER_PASS | docker login -u $DOCKER_USER --password-stdindocker push CircleCI-Public/circleci-demo-docker:$TAG

Note:TheCircleci.convenience imagesfor the Docker executor come with the Docker CLI pre-installed. If you are using a third-party image for your primary container that doesn’t already have the Docker CLI installed, thenyou will need to install itas part of your job before calling anydocker命令s.

# Install via apk on alpine based images - run: name: Install Docker client command: apk add docker-cli


  1. All commands are executed in theprimary-container。(第5行)
  2. Oncesetup_remote_dockeris called, a new remote environment is created, and your primary container is configured to use it. All docker-related commands are also executed in your primary container, but building/pushing images and running containers happens in the remote Docker Engine. (line 10)
  3. We enableDocker Layer Caching(DLC) here to speed up image building (note:the optiondocker_layer_caching: trueis available onPerformance and Custom plans, not the Free plan. DLC is available on CircleCI Server installations). (line 11)
  4. We use project environment variables to store credentials for Docker Hub. (line 17)

Docker version

To specify the Docker version, you can set it as aversionattribute:

-  setup_remote_docker:版本:19.03.13


  • 19.03.13
  • 19.03.12
  • 19.03.8
  • 18.09.3
  • 17.09.0-ce(默认)

Note:Theversionkey is not currently supported on CircleCI Server installations. Contact your system administrator for information about the Docker version installed in your remote Docker environment.


The job andremote dockerrun in separate environments. Therefore, Docker containers specified to run your jobs cannot directly communicate with containers running in remote docker.

Accessing services

It isnotpossible to start a service in remote docker and ping it directly from a primary container or to start a primary container that can ping a service in remote docker. To solve that, you’ll need to interact with a service from remote docker, as well as through the same container:

# ... - run: name: "Start Service and Check That it’s Running" command: | docker run -d --name my-app my-app docker exec my-app curl --retry 10 --retry-connrefused http://localhost:8080 # ...


#...  - 运行:|Docker Run -d  -  name my-app my-app docker运行--network容器:my-app适当/ curl --retry 10 --retry-connrefused http:// localhost:8080#...


It isnotpossible to mount a volume from your job space into a container in Remote Docker (and vice versa). You may use thedocker cp命令to transfer files between these two environments. For example, to start a container in Remote Docker using a config file from your source code:

- 运行:|# create a dummy container which will hold a volume with config docker create -v /cfg --name configs alpine:3.4 /bin/true # copy a config file into this volume docker cp path/in/your/source/code/app_config.yml configs:/cfg # start an application container using this volume docker run --volumes-from configs app-image:1.2.3

在这个年代ame way, if your application produces some artifacts that need to be stored, you can copy them from Remote Docker:

- 运行:|#使用应用程序启动容器#确保您不使用` -  -rm`选项,否则将在完成Docker运行后将丢失容器--name app app-movie:1.2.3  - 运行:|#应用程序容器完成后,直接从IT Docker CP应用程序:/输出/路径/ /您/作业/空间中复制工件

It is also possible to use or a similar image for backup and restore to spin up a container as shown in the following examplecircle-dockup.yml.config:

version: '2' services: bundler-cache: image: outstand/dockup:latest command: restore container_name: bundler-cache tty: true environment: COMPRESS: 'false' volumes: - bundler-data:/source/bundler-data

然后,样本circleci。Circleci./config.ymlsnippets below populate and back up thebundler-cache容器。

# Populate bundler-data container from circleci cache-restore_cache.:keys:-v4-bundler-cache  -  {{arch}}  -  {{.branch}}  -  {{校验和“gemfile.lock”}}-v4-bundler-cache-{{ arch }}-{{ .Branch }}-v4-bundler-cache-{{ arch }}-run:name:将Bundler缓存恢复为Docker卷命令:|NAME=bundler-cacheCACHE_PATH=~/bundler-cacheset -xmkdir -p $CACHE_PATHDocker撰写-f docker-compose.yml -f docker/circle-dockup.yml up --no-start $NAMEdocker cp $ cache_path /。$名称:/备份docker-compose -f docker-compose.yml -f docker / circle-dockup.yml向上--no-重新创建$名称Docker RM -F $名称#备份相同的卷圆缓存-run:name:Backing up bundler cache from docker volumes命令:|NAME=bundler-cacheCACHE_PATH=~/bundler-cacheset -xDocker撰写-f docker-compose.yml -f docker/circle-dockup.yml run --name $NAME $NAME backupdocker cp $NAME:/backup/. $CACHE_PATHDocker RM -F $名称-save_cache:key:v4-bundler-cache  -  {{arch}}  -  {{.branch}}  -  {{校验和“gemfile.lock”}}paths:-〜/ bundler-cache


什么时候a remote Docker environment is spun up, an SSH alias is created for you so you can SSH into the remote Docker virtual machine. This may be helpful for debugging your builds, or modifying the Docker or VM filesystem configuration. To SSH into the remote Docker VM, run the following within your project configuration job steps, or during a SSH rerun:


Note:上面显示的示例为您提供了一种方法,因为它们不起作用以来docker执行者。这种方法的替代方法是使用machineexecutor where volume mounts do work.

Thanks to ryansch for contributing this example.

See also

Docker Layer Caching