Integrating TeamCity with Container Managers
TeamCity integrates with container managers (Docker, Podman) on multiple levels.
The Docker build runner launches Docker commands and creates Docker images during a build.
The Docker Compose build runner starts services with the help of the Docker Compose tool during a build.
The Container Wrapper extension executes build steps inside containers. Supports Docker and Podman. Available for multiple runners.
The Run in Docker build feature allows you to run all build steps together in the same container.
The Docker Registry Connections build feature automatically signs in to container registries using Docker or Podman before starting a build. This feature also adds the Container Info tab of Build Results with the information about the images published to a 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.
tip
This page is about TeamCity instruments for integrating builds with Docker and Podman. If you want to learn how to run Docker inside a build agent container and read other information about the TeamCity Agent Docker images, read our documentation in Docker Hub.
To run a Docker- or Podman-related operation, a build agent must be able to use the docker or podman executable.
Docker can be installed on Linux, Windows, and macOS build agents.
On Linux, the Docker Registry Connections integration will run if the installed Docker is detected.
On Windows, the integration works for Linux and Windows container modes.
On macOS, the official Docker support for Mac should be installed for the user running the build agent.
Podman is a tool designed primarily for Linux. To run on Windows and macOS, Podman requires an installed Linux virtual machine ("Podman machine"). See the following article to learn more about installing Podman on different operating systems: Podman Installation Instructions.
Specify container registry domains in the
registries.conffile on your build agent machine. For example:unqualified-search-registries = ["docker.io"]. Podman and TeamCity require this list of registries to:Resolve full container addresses when a
podman ...command uses a short image name (for example,podman pull ubi8instead ofpodman pull registry.access.redhat.com/ubi8:latest).Successfully log in to a registry if your build configuration has the Docker Registry Connections build feature.
See the following article to learn more about the
registries.conffile: How to manage Linux container registries.If you're running Linux build agents configured to start automatically via systemd, enable user lingering to keep a user session running:
loginctl enable-linger my_agent_user.
Install Docker or Podman on your agent machines. For Windows and macOS agents, additionally requires a Podman machine.
To use the Docker Compose build runner, you also need to install Docker Compose.
TeamCity checks the following parameters to identify the available agent software:
container.engine— returns "docker", "podman" or "docker,podman", depending on which container manager is installed on the agent machine. If both Docker and Podman are installed, TeamCity uses Docker by default.teamcity.default.сontainer.engine— set this property to eitherdockerorpodmanto always use the desired tool. This property allows you to override the default logic that forces TeamCity to use Docker when both tools are available. You can set this property as a configuration parameter or as an individual agent's setting (in the buildAgent.properties file).docker.server.version,docker.version— return versions of installed Docker Engine and Docker CLI, respectively.podman.version— stores the version of installed Podman software.docker.server.osType,podman.osType— return the type of the agent OS. Supported values are "linux" (for both Linux and macOS agents) and "windows".dockerCompose.version— returns the Docker Compose file version, if the Docker Compose build step is used.
Depending on the exact Docker/Podman integration you utilize, TeamCity specifies different agent compatibility requirements. For instance, if your build configuration uses the Docker runner, this configuration can only run on agents that meet the docker.server.version exists requirement.
tip
If you are using the Command Line build step instead of the Docker runner, these parameters can be used as agent requirements to ensure your build is run only on the agents with Docker installed.
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 Registry Connections build feature, or
in a Docker or Docker Compose build step, or
in a build step with the enabled Container 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 сaches using the docker/podman system prune --volumes command. For Docker installations, this clean-up works for v.17.06.1 or later.
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:
##teamcity[dockerMessage type='dockerImage.push' value='<full_image_tag>,size:<size in bytes>,digest:<hash>']For example:
##teamcity[dockerMessage type='dockerImage.push' value='myRegistry/repo-test:17,size:2632,digest:sha256:8dc5a195c3dcdc7c288d16288ff3f9ab1d8a5a230e09afb9c8dc9215e861aa55']Since November 1st 2020, Docker Hub introduces download rate limits for public image pulls.
If your TeamCity builds use Container 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
If you have a Team or Pro Docker account, the number of pulls stays unlimited.
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 Force pull on each run 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.
While freeing disk space for 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.