Container Wrapper

Edit page Last modified: 07 November 2023

The Container Wrapper extension allows running a build step inside the specified Docker/LXC image. Images are pulled via docker pull or podman pull commands, depending on which container manager is installed on the agent that runs the build.

The extension is available for the following build runners:

tip

Container Wrapper is a part of the TeamCity-Docker/Podman integration toolset. Refer to this documentation article for information on software requirements, supported environments, and other common aspects of this integration: Integrating TeamCity with Container Managers.

Container Settings

In the Container Settings section of the build step settings, you can specify an 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 container

The image name as stated in Docker Hub or other registry. 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.

If an agent that runs the build has Podman installed instead of Docker, use either full image names (for example, docker.io/library/alpine:latest instead of alpine:latest), or ensure the registry domain is specified in the registries.conf file on your build agent machine. See also: How to manage Linux container registries.

Image platform

Select <Any> (default), Linux, or Windows. Note that Windows images are not supported by Podman.

Pull image explicitly

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

Additional run arguments

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

tip

In this field, you cannot reference environment variables using the %env.FOO_BAR% syntax because TeamCity does not pass environment variables from a build agent into a 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 Container Wrapper Works

Technically, the command of the build runner is wrapped in a shell script, and this script is executed inside a container with the docker run or podman run command. To view the details about the started process, text of the script, and so on, check the build log in Verbose mode.

The Container Wrapper maps paths to the build checkout directory and other agent directories like buildAgent/work, so that all these directories have the same location on a build agent and inside a Container Wrapper.

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

Build agents that use Docker execute the chown command at the end of each step running inside a container to restore the buildAgent user's permissions to access the checkout directory. This action prevents potential issues related to build agents being unable to remove no longer needed container files that were created with the root ownership. Agents using Podman do not perform this step.

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 the teamcity.docker.chown.enabled=false configuration parameter to the buildAgent.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 or Podman process, but it does not pass environment variables from the build agent, as they may not be relevant to the 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:

  1. Add a Command Line build step.

  2. Set the Run mode to Executable with parameters.

  3. In the Command executable field, specify the full path to the ENTRYPOINT in the target container.

  4. In Docker Settings, specify the name of the container.

TeamCity will start the specified Docker image with the defined ENTRYPOINT.

See also

Administrator's Guide