DEV Community

giveitatry
giveitatry

Posted on

Running TeamCity Agents on Bare Metal Linux

#cicd #devops #docker #linux

This article describes how to install and configure a TeamCity Build Agent on bare-metal Linux, with Java and Docker support, so the agent can run Docker-based builds reliably.

The guide assumes:

  • Linux (Ubuntu/Debian-based)
  • Root or sudo access
  • TeamCity Server already running

1. System Requirements

Hardware

  • CPU: 2 cores minimum (4+ recommended)
  • RAM: 4 GB minimum (8+ recommended for Docker builds)
  • Disk: ≥ 20 GB free

Software

  • Linux (Ubuntu 20.04+ recommended)
  • Java Runtime Environment
  • Docker Engine
  • TeamCity Build Agent

2. Update the System

Before installing anything, update the package index:

sudo apt update
sudo apt upgrade -y
Enter fullscreen mode Exit fullscreen mode

3. Install Java (Required by TeamCity Agent)

TeamCity agents require Java to run.

Install the default JRE:

sudo apt install -y default-jre
Enter fullscreen mode Exit fullscreen mode

Verify installation:

java -version
Enter fullscreen mode Exit fullscreen mode

Expected output:

openjdk version "11.x" or newer
Enter fullscreen mode Exit fullscreen mode

4. Install Docker Engine

Docker is required if the agent will run Docker builds.

Install Docker from Ubuntu repositories: 

sudo apt install -y docker.io
Enter fullscreen mode Exit fullscreen mode

Enable and start Docker:

sudo systemctl enable docker
sudo systemctl start docker
Enter fullscreen mode Exit fullscreen mode

Verify Docker is running:

sudo docker ps
Enter fullscreen mode Exit fullscreen mode

5. Allow the Agent User to Run Docker

Docker access is controlled via the Unix socket:

/var/run/docker.sock
Enter fullscreen mode Exit fullscreen mode

Only users in the docker group can access it.

Add the agent user to the docker group

Example (agent user = risto):

sudo usermod -aG docker risto
Enter fullscreen mode Exit fullscreen mode

⚠️ Important:
Group membership changes apply only after logout/login.

➡️ Log out and log back in (or reboot the machine).

Verify:

groups
Enter fullscreen mode Exit fullscreen mode

You must see:

docker
Enter fullscreen mode Exit fullscreen mode

Test Docker access without sudo:

docker ps
Enter fullscreen mode Exit fullscreen mode

6. Install the TeamCity Build Agent

6.1 Download the Agent Package

On the agent machine:

mkdir -p /opt/teamcity-agent
cd /opt/teamcity-agent
Enter fullscreen mode Exit fullscreen mode

Download from your TeamCity server:

wget http://<TEAMCITY_SERVER>:8111/update/buildAgent.zip
Enter fullscreen mode Exit fullscreen mode

Unpack:

unzip buildAgent.zip
Enter fullscreen mode Exit fullscreen mode

7. Configure the Build Agent

7.1 Configure Server Connection

Edit the agent configuration file:

nano conf/buildAgent.properties
Enter fullscreen mode Exit fullscreen mode

Set the TeamCity server URL:

serverUrl=http://<TEAMCITY_SERVER>:8111
Enter fullscreen mode Exit fullscreen mode

(Optional but recommended)

name=baremetal-agent-01
workDir=../work
tempDir=../temp
systemDir=../system
Enter fullscreen mode Exit fullscreen mode

7.2 Docker Detection (Important)

TeamCity automatically detects Docker at agent startup.

Requirements:

  • Docker installed
  • Docker daemon running
  • Agent user can run docker ps

No extra Docker configuration is required if permissions are correct.

8. Start the Agent

Run the agent manually the first time:

bin/agent.sh start
Enter fullscreen mode Exit fullscreen mode

Check logs:

tail -f logs/teamcity-agent.log
Enter fullscreen mode Exit fullscreen mode

9. Authorize the Agent in TeamCity

In the TeamCity web UI:

Agents → Unauthorized
Enter fullscreen mode Exit fullscreen mode

Authorize the new agent.

Once authorized, verify agent parameters:

Agents → <agent> → Parameters → System Properties
Enter fullscreen mode Exit fullscreen mode

You should see:

docker.server.osType = linux
docker.server.version = 26.x
docker.client.version = 26.x
java.runtime.version = 11.x
Enter fullscreen mode Exit fullscreen mode

10. Common Problems and Fixes

❌ Docker not detected by TeamCity

Cause: Agent started before Docker was installed or permissions fixed.

Fix:

sudo systemctl restart docker
bin/agent.sh restart
Enter fullscreen mode Exit fullscreen mode

❌ permission denied /var/run/docker.sock

Cause: Agent user not in docker group or session not refreshed.

Fix:

sudo usermod -aG docker <agent-user>
# logout + login
bin/agent.sh restart
Enter fullscreen mode Exit fullscreen mode

❌ Agent runs but Docker builds never start

Check unmet requirements:

docker.server.version exists
docker.server.osType contains linux
Enter fullscreen mode Exit fullscreen mode

If missing → Docker not visible to agent.

11. Security Notes

  • Adding a user to the docker group grants root-equivalent access
  • Use dedicated agent users
  • Restrict agent responsibilities when possible

12. Summary

To run TeamCity agents on bare metal with Docker:

  1. Install Java (default-jre)
  2. Install Docker (docker.io)
  3. Add agent user to docker group
  4. Log out and back in
  5. Configure buildAgent.properties
  6. Start and authorize the agent

Top comments (0)