Docker Wrapper

Edit page

TeamCity provides the Docker Wrapper extension for Command Line, Maven, Ant, Gradle, .NET CLI (dotnet), and PowerShell runners. This extension allows running a build step inside the specified Docker image. Each of the supported runners has the dedicated Docker settings section.

Requirements

The integration requires Docker installed on the build agents.

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.

note

  • On Linux, the 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.

Docker Settings

In the Docker Settings section of the build step settings, you can specify a Docker image which will be used to run the build step. Once an image is specified, all the following options become available.

Setting

Description

Run step within Docker container

Specify a Docker image name as stated in the Docker Hub. TeamCity will start a container from the specified image and will try to run this build step within this container.

For example, ruby:2.4 will run the step within the Ruby container, version 2.4.

Docker image platform

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

Pull image explicitly

If enabled, the image will be pulled from the Hub repository via docker pull <imageName> before the docker run command is launched.

Additional docker run arguments

Allows specifying additional options for docker run. The default argument is --rm, but you can provide more, for instance, add an additional volume mapping.

note

In this field, you cannot reference environment variables using %env.FOO_BAR% syntax because TeamCity does not pass environment variables from a build agent into a Docker container.

If you need to reference an environment variable on an agent, define the configuration parameter system.FOO_BAR=env_var_value in buildAgent.properties and reference it via %system.FOO_BAR%.

How It Works

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

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

At the end of the build step with the Docker wrapper, a build agent runs the chown command to restore access of the buildAgent user to the checkout directory. This mitigates a possible problem when the files from a Docker container are created 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 the previous Docker Compose build step, this network is passed to the started docker run command with the --network switch.

Environment Variables Handling

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