DEV Community

giveitatry
giveitatry

Posted on

Running TeamCity with a Docker-Capable Agent Using Docker Compose

#docker #teamcity

TeamCity is a powerful CI/CD server from JetBrains, and running it inside Docker simplifies setup, upgrades, and isolation. This guide shows how to set up TeamCity Server and a TeamCity Agent capable of building Docker images.

Prerequisites

Before you start, ensure you have:

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

Step 1: Create a directory structure

It’s best practice to separate your data, logs, and agent configuration:

mkdir -p teamcity/{data,logs,agent}
cd teamcity
Enter fullscreen mode Exit fullscreen mode

Your directory structure should look like this:

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

Step 2: Create the Docker Compose file

Create a file called docker-compose.yml with the following content:

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
Enter fullscreen mode Exit fullscreen mode

Key points:

  1. Server volumes:
  • ./data stores TeamCity server data and build history.
  • ./logs keeps server logs persistent across container restarts.
  1. Agent setup:
  • The agent runs as root to have permissions to use the host Docker socket.
  • /var/run/docker.sock is mounted to allow the agent to access the host Docker daemon.
  • SERVER_URL points the agent to the server.

Step 3: Start TeamCity

Run:

docker compose up -d
Enter fullscreen mode Exit fullscreen mode
  • -d runs containers in the background.
  • The server will be available at http://localhost:8111.
  • The agent container will automatically try to connect to the server.

Step 4: Initial TeamCity setup

  1. Open your browser and go to: 
http://localhost:8111
Enter fullscreen mode Exit fullscreen mode
  1. Follow the web setup wizard:
  • Confirm the data directory (mapped to ./data)
  • Choose a database (internal database is fine for testing)
  • Accept the license
  • Create the initial admin account

Step 5: Authorize the agent

  1. Go to Agents → Unauthorized in the TeamCity UI.
  2. Click Authorize for your agent.
  3. Once authorized, the agent will show as Connected and Compatible.

Step 6: Verify Docker capability

Open a terminal inside the agent container:

docker exec -it teamcity-agent docker version
Enter fullscreen mode Exit fullscreen mode

You should see the Docker client and server versions. If so, the agent can now build Docker images.

Step 7: Configure a Docker build in TeamCity

You can use Command Line or Docker runner build steps.

Example Command Line step: 

docker build -t my-app:%build.number% .
docker push my-app:%build.number%
Enter fullscreen mode Exit fullscreen mode

Example Docker Runner step:

  1. Add a Docker build step in the UI.
  2. Set the Dockerfile path.
  3. Set the image name.
  4. TeamCity will use the agent’s Docker access to build images.

Step 8: Recommended best practices

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

Step 9: Stopping and restarting

To stop:

docker compose down
Enter fullscreen mode Exit fullscreen mode

To restart:

docker compose up -d
Enter fullscreen mode Exit fullscreen mode

The agent will reconnect automatically after restart.

✅ Summary

With this setup:

  • You have a fully functional TeamCity server running in Docker.
  • Your TeamCity agent can build Docker images using the host Docker daemon.
  • Data and logs persist across restarts, and you can expand with more agents if needed.

This setup is ideal for testing, development, and small production environments.

Top comments (0)