Running TeamCity with a Docker-Capable Agent Using Docker Compose

Source: Dev.to

Prerequisites

• Docker installed and running
• Docker Compose installed
• Sufficient permissions to run Docker commands on your host
• A terminal/command‑line interface

Directory layout

mkdir -p teamcity/{data,logs,agent}
cd teamcity

Your directory should look like this:

teamcity/
├── docker-compose.yml
├── data/       # Server persistent data
├── logs/       # TeamCity logs
└── agent/      # Agent configuration

docker-compose.yml

version: "3.8"

services:
  teamcity-server:
    image: jetbrains/teamcity-server:2023.11.4
    container_name: teamcity-server
    ports:
      - "8111:8111"
    volumes:
      - ./data:/data/teamcity_server/datadir
      - ./logs:/opt/teamcity/logs
    restart: unless-stopped

  teamcity-agent:
    image: jetbrains/teamcity-agent:2023.11.4
    container_name: teamcity-agent
    user: root
    environment:
      - SERVER_URL=http://teamcity-server:8111
    volumes:
      - ./agent:/data/teamcity_agent/conf
      - /var/run/docker.sock:/var/run/docker.sock
    depends_on:
      - teamcity-server
    restart: unless-stopped

Explanation

• Server volumes

  • ./data stores TeamCity server data and build history.
  • ./logs keeps server logs persistent across container restarts.

• Agent setup

  • Runs as root to have permission to use the host Docker socket.
  • /var/run/docker.sock is mounted so the agent can access the host Docker daemon.
  • SERVER_URL points the agent to the server.

Starting the stack

docker compose up -d

• -d runs the containers in the background.
• The server will be reachable at .
• The agent container will automatically try to connect to the server.

Initial web setup

1. Open in a browser.
2. Follow the wizard:
   • Confirm the data directory (mapped to ./data).
   • Choose a database (the internal DB is fine for testing).
   • Accept the license.
   • Create the initial admin account.

Authorizing the agent

1. In the TeamCity UI go to Agents → Unauthorized.
2. Click Authorize for your agent.

The agent should now appear as Connected and Compatible.

Verify Docker access inside the agent

docker exec -it teamcity-agent docker version

You should see both Docker client and server versions, confirming that the agent can build Docker images.

Building Docker images

You can use a Command Line or Docker runner build step, e.g.:

docker build -t my-app:%build.number% .
docker push my-app:%build.number%

In the UI:

1. Add a Docker build step.
2. Set the Dockerfile path and the image name.

TeamCity will use the agent’s Docker access to build and push images.

Best practices

• Keep the /data folder on fast, persistent storage.
• Back up TeamCity server data regularly.
• Limit access to the TeamCity server and Docker socket; running the agent as root gives full control over Docker on the host.
• For production, consider a Docker‑in‑Docker setup or a remote Docker host for better isolation.

Stopping and restarting

docker compose down          # stop
docker compose up -d         # start (agent reconnects automatically)

Summary

• Fully functional TeamCity server running in Docker.
• Docker‑capable TeamCity agent can build images using the host Docker daemon.
• Data and logs persist across restarts; the setup can be expanded with additional agents.
• Ideal for testing, development, and small production environments.