Integrating TeamCity with Docker
TeamCity integration with Docker includes:
The Docker build runner to launch Docker commands and create Docker images during a build.
The Docker Compose build runner to start services with the help of the Docker Compose tool during a build.
The Docker Wrapper extension to execute build steps inside a Docker container. Available for multiple runners.
The Docker Support build feature to automatically sign in to a Docker registry before starting a build. This feature also adds the Docker Info tab of Build Results with the information about the images published to the Docker registry during the build.
You can learn more details about the listed tools in the dedicated Help articles, linked above. The following article contains information common to these tools.
Requirements
The integration requires Docker to be installed on the build agents. To use the Docker Compose build runner, you also need to install Docker Compose.
TeamCity periodically checks if Docker is available on active build agents. Based on the docker.server.version and docker.version variables received from the agents, TeamCity distributes builds that use Docker only between agents with the installed Docker engine.
If a build configuration uses the Docker runner or the Docker Wrapper extension, TeamCity automatically adds the docker.server.version agent compatibility requirement for this configuration.
Supported Environments
TeamCity Docker Support can run on Windows, Linux, and macOS build agents. It uses the docker executable on the build agent machine, so it should be runnable by the build agent user.
Parameters Reported by Agent
During the build, the build agent can report the following Docker-related parameters:
Parameter | Description |
|---|---|
| The Docker CLI version. |
| The Docker Compose file version, if the Docker Compose build step is used. |
| The Docker Engine version. |
| The Docker Engine OS platform. Supported values: |
Docker Disk Space Cleaner
Docker Disk Space Cleaner is an extension to the Free Disk Space build feature ensuring a necessary amount of disk space for a build.
TeamCity regularly cleans up its related Docker images which were tagged/pulled:
in a build with the Docker Support build feature, or
in a Docker or Docker Compose build step, or
in a build step with the enabled Docker Wrapper extension.
For such builds,
A TeamCity agent tracks Docker images tagged or pulled during the builds (the list of images is stored in the
buildAgent/system/docker-used-images.datfile).During clean-up / freeing disk space, the TeamCity agent tries to remove these images if they have not been used within 3 days (or 1 or 0 days, on subsequent attempts to free the disk space).
Besides, TeamCity cleans local Docker Caches using the docker system prune --volumes command. Works for Docker v.17.06.1 or later.
Service Message to Report Pushed Image
If, for some reason, TeamCity cannot determine that an image has been pushed, a user can send a special service message to report this information to the TeamCity server:
For example:
Conforming with Docker download rate limits
Since November 1st 2020, Docker Hub introduces download rate limits for public image pulls.
If your TeamCity builds use Docker Wrapper or Docker Compose to pull images from Docker Hub, make sure these pulls do not exceed the following limits:
Anonymous Docker users: 100 pulls per 6 hours
Docker users with the Free plan: 200 pulls per 6 hours
Paid Docker subscription users: 5000 pulls per 24 hours
A regular TeamCity agent stores a once pulled image in its cache. This allows running an indefinite number of builds using the same pulled image on a regular basis.
However, there are few cases to consider:
If you are using cloud agents, all required images will be downloaded every time a new cloud agent is launched.
If the Pull image explicitly option is enabled in the build step settings, the image will be downloaded in every new build run, even on a local agent. We recommend that you disable this option to prevent reaching the rate limit.
During the Free Disk Space stage of the build, TeamCity may clean up old unused Docker images from the local cache.
If previously your builds were accessing Docker Hub anonymously, you can double the number of allowed pulls by creating a Free Docker user profile and configuring a Docker connection in your TeamCity project. TeamCity agents will be able to use this connection to authenticate in Docker Hub before each build.