Run in Docker

Edit pageLast modified: 02 March 2025

The Run in Docker build feature allows you to run all steps of a build configuration in the same Docker or Linux container. Below is the list of build steps that can be launched inside a container:

Steps that are not included in this list will be run outside of the specified container.

note

Run in Docker 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.

Settings

TeamCity provides two options to run build steps inside containers:

  • Run in Docker build feature — specifies global container settings common for all build steps of this configuration.

  • Container Wrapper — allows you to run one individual step in the required container.

Both "Run in Docker" and "Container Wrapper" expose identical settings.

Image name

The image name as stated in DockerHub or other registry. TeamCity will start a container from the specified image and will try to run the required build configuration within this container. For example, `ruby:2.4` will run the build configuration 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.

Force pull on each run

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

Additional run arguments

Allows specifying additional options for the docker/podman run command. The default argument is --rm, but you can provide more. For example, add a custom volume mapping.

note

If you need to utilize environment variables in this field (for example, %env.FOO%), note that TeamCity passes to containers only those variables that are declared in build configurations and projects. Agent-specific environment variables declared in the buildAgent.properties file are not passed to containers.

If you need a parameter declared in this file, do the following:

  1. Define a system property (system.FOO=BAR) in buildAgent.properties.

  2. Add a build configuration parameter with the system.FOO name and %system.FOO% value.

  3. Reference the system property as %system.FOO% in the "Additional run arguments" field.

  4. If you need to use the same value as an environment variable in your build script, you can also add a build configuration parameter with the env.FOO name and %system.FOO% value.

Kotlin DSL

The snippet below illustrates how to configure the Run in Docker feature in Kotlin DSL:

object BuildConf : BuildType({
    name = "BuildConf"
    // ...
    features {
        runInDocker {
            dockerImage = "python:latest"
            dockerImagePlatform = RunInDockerBuildFeature.ImagePlatform.Linux
            dockerPull = true
            dockerRunParameters = "-a stdin -a stdout -i -t ubuntu /bin/bash"
        }
    }
})