Docker Wrapper
The Docker Wrapper extension allows running a build step inside the specified Docker image.
The extension is available for the following build runners:
Each of the supported runners has the dedicated Docker settings section.
tip
Docker Wrapper is a part of the TeamCity-Docker integration toolset. Refer to this page for information on software requirements, supported environments, and other common aspects of this integration.
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 the image is specified, the following options become available.
Setting | Description |
---|---|
Run step within Docker container | Specify a Docker image name as stated in Docker Hub. TeamCity will start a container from the specified image and will try to run this build step within this container. For example, |
Docker image platform | Select <Any> (default), Linux, or Windows. |
Pull image explicitly | If enabled, the image will be pulled from the Hub repository via |
Additional docker run arguments | Allows specifying additional options for the
|
How Docker Wrapper 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 build checkout directory and most build agent directories are mapped inside the Docker process.
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.
Restoring File Ownership on Linux
At the end of each build step performed inside a Docker wrapper, a build agent runs the chown
command to restore the access of the buildAgent
user to the checkout directory. This is done to prevent a potential problem when the files from a Docker container are created with the root
ownership and cannot be removed by the build agent later.
By default, a TeamCity agent uses the busybox
image from Docker Hub to run the chown
command. You can specify an alternative image name with the teamcity.internal.docker.busybox
parameter, either in the buildAgent.properties
file or in the build configuration parameters.
tip
You may want to disable restoring the file ownership. For instance, if the
userns-remap
package is used for handling ownership of files created under Docker. For this, add theteamcity.docker.chown.enabled=false
configuration parameter to thebuildAgent.properties
file. As a result, TeamCity will not try to restore permissions of the files at the end of the build.
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 the Verbose mode in the build log.
Setting Image Entrypoint
If a Docker image does not define an ENTRYPOINT
, you can use still run a container with an ENTRYPOINT
from the command line:
Add a Command Line build step.
Set the Run mode to Executable with parameters.
In the Command executable field, specify the full path to the
ENTRYPOINT
in the target Docker container.In Docker Settings, specify the name of the Docker container.
TeamCity will start the specified Docker image with the defined ENTRYPOINT
.