TeamCity 2019.1 Help

Integrating TeamCity with Docker

On this page:

TeamCity comes with Docker Support, implemented as a bundled plugin.

Requirements

The integration requires Docker installed on the build agents. Docker Compose also needs to be installed to use the Docker Compose build runner.

Supported Environments

TeamCity-Docker support can run on Mac, Linux, and Windows build agents. It uses the 'docker' executable on the build agent machine, so it should be runnable by the build agent user.

Since version 2018.2, TeamCity has switched from Oracle Java to OpenJDK 8 (by AdoptOpenJDK). All Docker images have been updated to support OpenJDK.

Parameters Reported by Agent

During the build, the build agent reports the following parameters:

Parameter

Description

docker.version

The Docker CLI version

dockerCompose.version

The Docker Compose file version if the Docker Compose build step is used

docker.server.version

The Docker Engine version

docker.server.osType

The Docker Engine OS platform, can have the linux or windows value

If you are using the Command Line Build step (and not the TeamCity-provided docker steps), these parameters can be used as agent requirements to ensure your build is run only on the agents with Docker installed.

Features

Team–°ity-Docker integration provides the following features which facilitate working with Docker under TeamCity:

Docker Support Build Feature

Adding this build feature will enable docker events monitoring: such operations as docker pull, docker run will be detected.
The build feature adds the Docker Info tab to the build results page providing information on Docker-related operations. It also provides the following options:

  • the ability to clean-up the images

  • automatic login to an authenticated registry before the build and logout of it after the build

These options require a configured connection to a docker registry:

dockerSupport.png

Clean-up of images

If you have a build configuration which publishes images, you need to remove them at some point. You can select the corresponding option and instruct TeamCity to remove the images published by a certain build when the build itself is cleaned up. It works as follows: when an image is published, TeamCity stores the information about the registry of the images published by the build. When the server clean-up is run and it deletes the build, all the configured connections are searched for the address of this registry and the images published by the build are cleaned up using the credentials specified in the connection found.

Automatic Login to/Logout of Docker Registry

If you need to log in to a registry requiring authentication before a build, select the corresponding option and a connection to Docker configured in the project settings.
Automatic logout will be performed after the build finishes.

Docker Connection for a Project

The Project Settings | Connections page allows you to configure a connection to docker.io (default) or a private Docker registry. More than one connection can be added to the project. The connection will be available in all the subprojects and build configurations of the current project.

Registry Address Format

By default, https://docker.io is used.

To connect to a registry, use the following format: [http(s)://]hostname:port.

If the protocol is not specified, the connection over https is used by default.

Connecting to Private Cloud Registry

  • TeamCity supports the Azure container registry storing Docker images; you can authenticate using Service principal (the principal ID and password are used as connection credentials) or Admin account.

  • Since TeamCity 2018.1, Amazon Elastic Container Registry (AWS ECR) is supported: specify the AWS region and your AWS Security Credentials when configuring the connection.

Connecting to Insecure Registry

To connect to an insecure registry:

  1. Configure all TeamCity agents where Docker is installed to work with insecure repositories as stated Docker documentation. This is sufficient to allow the connection to the private registry over http.

  2. To connect to an insecure registry over https with a self-signed certificate, in addition to the step above, import the self-signed certificate to the JVM of the TeamCity server as described here. You can consult the Docker documentation on using self-signed certificates.

Docker Runner

The Docker runner supports the build, push, tag Docker commands.

When creating TeamCity projects/ build configurations from a repository URL, the runner is offered as build step during auto-detection, provided a Dockerfile is present in the VCS repository.

Docker Command

Here is a list of the docker commands. Depending on the selected command, the settings below will vary.

Command

Parameter

Description

build

Dockerfile source

Depending on the selected source, the settings below will vary. The available options include File, a URL or File content.

Path to file

Available if File is selected as the source. Specify the path to the Docker file. The path should be relative to the checkout directory.

Context folder

Available if File is selected as the source. Specify the context for the docker build. If blank, the enclosing folder for Dockerfile will be used.

URL to file

Available if URL is selected as the source. The URL can refer to three kinds of resources: Git repositories, pre-packaged tarball contexts, and plain text files. See Docker documentation for details.

File Content:

Available if the file cis selected as the source. You can enter the content of the Dockerfile into the field.

Image platform

Select <Any> (default), Linux or Windows.

Image name:tag

Provide a newline-separated list of image name:tag(s)

Additional arguments for 'build' command

Supply additional arguments to the docker build command. See Docker documentation for details.

push

Remove image from agent after push

If selected, TeamCity will remove the image with docker rmi at the end of the step

Image name:tag

Provide a newline-separated list of image name:tag(s)

other

Command name

Docker sub-command, like push or tag. For run, use Docker Wrapper

Working directory

Additional arguments for the command

Additional arguments that will be passed to the docker command.

Docker Compose Runner

The runner allows starting Docker Compose build services and shutting down those services at the end of the build.

The Docker Compose runner supports one or several Docker Compose YAML file(s) with a description of the services to be used during the build. The path to the docker-compose.yml file(s) should be relative to the checkout directory. When specifying several files, separate them with a space.

The executed commands are:

# The commands are executed with the current working directory, where the docker-compose file resides. docker-compose -f <docker-compose.yml> [-f <docker-compose2.yml>] up -d # At the end of the build, for each docker compose build step the build agent will run: docker-compose -f <docker-compose.yml> [-f <docker-compose2.yml>] down -v

If the checkbox pull image explicitly is enabled, docker-compose pull will be run before the docker-compose up command.

When using Docker Compose with images which support HEALTHCHECK, TeamCity will wait for the healthy status of all containers, which support this parameter.

If the start of Docker Compose was successful, the TeamCity agent will register the TEAMCITY_DOCKER_NETWORK environment variable containing the name of the Docker Compose default network. This network will be passed transparently to the Docker Wrapper when used in some build runners.

Docker Wrapper

TeamCity provides the Docker Wrapper extension for Command Line, Maven, Ant, and Gradle runners. Each of the supported runners has the dedicated Docker settings section.

Docker Settings

In this section, you can specify a Docker image which will be used to run the build step. Once an image is specified, all the following options are available:

Setting

Description

Run step within Docker container

Specify a Docker image here. TeamCity will start a container from the specified image and will try to run this build step within this container.

Docker image platform

Select <Any> (default), Linux or Windows.

Pull image explicitly

If the checkbox is enabled, docker pull <imageName> will be run before the docker run command.

Additional docker run arguments

The Edit arguments field allows specifying additional options for docker run. The default argument is --rm, butyou can provide more, for instance, to add an additional volume mapping.

How It Works

Technically, the command of the build runner is wrapped in a shell script, and this script is executed inside a Dockercontainer with the docker run command. All the details about the started process, text of the script etc. are writteninto the build log (the Verbose mode enables viewing them).

The checkout directory and most build agent directories are mapped inside the Docker process.

At end of the build step with the Docker wrapper, a build agent runs the chown command to restore access of thebuildAgent user to the checkout directory. This mitigates a possible problem when the files from a Docker container arecreated with the 'root' ownership and cannot be removed by the build agent later.

If the process environment contains the TEAMCITY_DOCKER_NETWORK environment variable set by previousDocker Compose build step, this network is passed to the started docker run commandwith the --network switch.

Environment Variables Handling

TeamCity passes environment variables from the build configuration into the docker process, but it does not passenvironment variables from the build agent, as they may be not relevant to docker container environment. The list of thepassed environment variables can be seen in Verbose mode in the build log.

Docker Disk Space Cleaner

Docker Disk Space Cleaner is an extension to the Free Disk Space build feature ensuring a certain amount of disk space for a build.

Since 2018.2 TeamCity performs regular clean-up of Docker images, related to TeamCity:

  • The TeamCity agent tracks docker images tagged or pulled during builds (the list of images is stored in the buildAgent/system/docker-used-images.dat file).

  • During cleanup / freeing disk space, TeamCity agent tries to remove these images if they were not used within 3 days, 1 day, 0 on subsequent attempts to free disk space.

Besides that, TeamCity cleans local Docker Caches using the command:

  • Since 2018.1.2: docker system prune --volumes. Works for Docker v.17.06.1 or later.

  • Before 2018.1.2: docker system prune -a

Service Message to Report Pushed Image

If TeamCity (for some reason) cannot determine that an image was 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']
Last modified: 11 June 2019