Skip to content

Latest commit

 

History

History
191 lines (137 loc) · 11.2 KB

README.md

File metadata and controls

191 lines (137 loc) · 11.2 KB
Raw

TeamCity Build Agent

This is an official JetBrains TeamCity build agent image.

More details about tags and components are here .

The TeamCity build agent connects to the TeamCity server and spawns the actual build processes. You can use the jetbrains/teamcity-server image to run a TeamCity server. To learn how you can start the TeamCity server together with agents in one go, see these Docker Compose samples.

This image adds a TeamCity agent suitable for Java development. It is based on jetbrains/teamcity-minimal-agent but gives you more benefits, e.g.

  • client-side checkout if you use 'git' or 'mercurial'
  • more bundled build tools
  • 'docker-in-docker' on Linux

How to Use This Image

Pull the TeamCity image from the Docker Hub Repository:

jetbrains/teamcity-agent

  and use the following command to start a container with TeamCity agent running inside

a Linux container:

docker run -e SERVER_URL="<url to TeamCity server>"  \ 
    -v <path to agent config folder>:/data/teamcity_agent/conf  \      
    jetbrains/teamcity-agent

  or a Windows container:

docker run -e SERVER_URL="<url to TeamCity server>"
    -v <path to agent config folder>:C:/BuildAgent/conf
    jetbrains/teamcity-agent

  where <url to TeamCity server> is the full URL for TeamCity server, accessible by the agent. Note that "localhost" will generally not work as it will refer to the "localhost" inside the container.
<path to agent config folder> is the host machine directory to serve as the TeamCity agent config directory. We recommend providing this binding in order to persist the agent configuration, e.g. authorization on the server. Note that you should map a different folder for every new agent you create.

Since version 2020.1, TeamCity agent Docker images run under a non-root user. Refer to our upgrade notes for information on possible affected use cases.

When you run the agent for the first time, you should authorize it via the TeamCity server UI: go to the Unauthorized Agents page in your browser. See more details. All information about agent authorization is stored in the agent's configuration folder. If you stop the container with the agent and then start a new one with the same config folder, the agent's name and authorization state will be preserved.

A TeamCity agent does not need manual upgrade: it will upgrade itself automatically on connecting to a server.

Agent Image Environment Variables

  • SERVER_URL – URL of the TeamCity server agent will connect to
  • AGENT_NAME – (optional) Name of the agent in TeamCity UI, autogenerated if omitted
  • AGENT_TOKEN – (optional) Agent authorization token, if unset, the agent should be authorized via TeamCity UI.
  • OWN_ADDRESS – (optional, Linux-only) IP address build agent binds to, autodetected
  • OWN_PORT – (optional, Linux-only) Port build agent binds to, 9090 by default
  • DOCKER_IN_DOCKER – (optional, Linux-only) Run Docker within Docker.

Preserving Checkout Directories Between Builds

When build agent container is restarted, it re-checkouts sources for the builds.

To avoid this, you should pass a couple of additional options to preserve build agent state between restarts:

  1. Preserve checked out sources (-v /opt/buildagent/work:/opt/buildagent/work)
  2. Keep internal build agent caches (-v /opt/buildagent/system:/opt/buildagent/system)

You can use other than /opt/buildagent/ source path prefix on the host machine unless you're going to use Docker Wrapper via docker.sock (see below).

Running Builds Which Require Docker

You have two options if you need a docker daemon available inside your builds.

One is to use docker server from the host, which starts teamcity agent container (docker-out-of-docker). Another is to run a docker server inside teamcity agent container (docker-in-docker).

NOTE: both of these options require extra trust to your builds, as a build may get root access to the host where the TeamCity agent container is running. Read more about Docker security at OWASP and review the TeamCity security notes.

Using the docker from the host

This is the approach of passing docker socket into the started agent, with the -v /var/run/docker.sock:/var/run/docker.sock volume parameter.

In this case you will benefit from the docker caches shared between the host and all your containers but there is a security concern: your build might actually harm your host Docker, so use it at your own risk

docker run -e SERVER_URL="<url to TeamCity server>"  \
    -u 0 \
    -v <path to agent config folder>:/data/teamcity_agent/conf \
    -v /var/run/docker.sock:/var/run/docker.sock  \
    -v /opt/buildagent/work:/opt/buildagent/work \
    -v /opt/buildagent/temp:/opt/buildagent/temp \
    -v /opt/buildagent/tools:/opt/buildagent/tools \
    -v /opt/buildagent/plugins:/opt/buildagent/plugins \
    -v /opt/buildagent/system:/opt/buildagent/system \
    jetbrains/teamcity-agent

Volume options starting with -v /opt/buildagent/ are required if you want to use Docker Wrapper on this build agent. Without them, the corresponding builds with the enabled docker wrapper (for the Command Line, Maven, Ant, Gradle, .NET, and PowerShell runners) will not work. Unfortunately, using several docker-based build agents from the same host is not possible.

If you omit these options, you can run several build agents (you need to specify different <path to agent config folder> paths for them), but Docker Wrapper won't work on such agents.

The problem is, that multiple agent containers would use the same (/opt/buildagent/*) directories as they are mounted from the host machine to the agent container and that the docker wrapper mounts the directories from the host to the nested docker wrapper container. And, you cannot use multiple agent containers with different paths on the host as the docker wrapper would still try to map the paths as they are in the agent container, but from the host machine to the nested docker wrapper container. To make several agents work with docker wrapper and docker.sock option, one have to build different teamcity-agent docker images with different paths of teamcity-agent installation inside those images (like /opt/buildagentN), and start those images with corresponding parameters like -v /opt/buildagent1/work:/opt/buildagent1/work etc.

Starting docker server inside agent container

With this option teamcity agent container starts its own new Docker daemon.

In this case the container should be run with the —-privileged flag, which is also risky from the security perspective.

With this approach, you have to use a TeamCity agent image with the -linux-sudo tag suffix:

docker run -e SERVER_URL="<url to TeamCity server>"  \
    -u 0 \
    -v <path to agent config folder>:/data/teamcity_agent/conf \
    -v docker_volumes:/var/lib/docker \
    --privileged -e DOCKER_IN_DOCKER=start \    
    jetbrains/teamcity-agent:2023.11-linux-sudo

The option -v docker_volumes:/var/lib/docker is related to the case when the aufs filesystem is used and when a build agent is started from a Windows machine (related issue).
If you want to start several build agents, you need to specify different volumes for them, like -v agent1_volumes:/var/lib/docker, -v agent2_volumes:/var/lib/docker.

Windows Containers Limitations

The details on the known problems in Windows containers are available in the TeamCity documentation.

Customization

Leveraging existing Dockerfiles. Please, refer to custom TeamCity Agent Images for more information.

Manually. To customise the Agent image manually, please follow the procedure below.

  1. Create a container.
docker run -e SERVER_URL="<url to TeamCity server>"  \ 
    -v <path to agent config folder>:/data/teamcity_agent/conf  \
    --name="my-customized-agent"  \
    jetbrains/teamcity-minimal-agent  \
  1. Enter the container
docker exec -it my-customized-agent bash

  1. Please make any required adjustments as needed

  2. Exit and create a new image from the container:

docker commit my-customized-agent <the registry where you what to store the image>

License

The image is available under the TeamCity license. TeamCity is free for perpetual use with the limitation of 100 build configurations (jobs) and 3 agents. Licensing details.

Troubleshooting

Apt manager distrusts the apt Perforce repository key

This issue may occur for Docker images released prior to August 14, 2023 (TW-83304).

The Perforce Package key expired and was updated on August 14, 2023. This results in the following error that occurs if you modify the apt packages in images based on containers released before this date:

$ apt-get update
...
Err:15 https://package.perforce.com/apt/ubuntu focal InRelease                                                                                                                                                                          
  The following signatures were invalid: EXPKEYSIG 7123CB760FF18869 Perforce Software (Package Signing) <[email protected]>
…

To avoid this issue, execute this command in a container or include it in a Docker image build step before altering packages:

sudo apt-key adv --fetch-keys https://package.perforce.com/perforce.pubkey

Feedback

Report issues of suggestions to the official TeamCity issue tracker.

Other TeamCity Images