Advanced Topics

A production-ready Java microservice pipeline integrating everything from Phases 1–14:

Design principles applied

• Compile once, test in parallel — avoids redundant builds
• Composite build as GitHub gate — one status check covers the full pipeline
• Package only on main branch — feature branches build and test but don't produce artifacts
• Staging is automated; production is manual with prompt confirmation
• All stages use snapshot dependency on Compile — guaranteed same revision throughout

TeamCity doesn't have a native matrix syntax like GitHub Actions, but you can achieve matrix builds by creating one build configuration per combination and grouping them under a composite.

Pattern: test against multiple JDK versions

# Create one build config per JDK version using templates:
# Template: Maven-Test-Template
#   Parameter: jdk.version (required)
#   Agent requirement: java.version starts with %jdk.version%
#   Maven goals: test
#   Artifact: target/surefire-reports/**/* => test-reports/%jdk.version%

# Apply template to create:
# Test-JDK8   → jdk.version=1.8
# Test-JDK11  → jdk.version=11
# Test-JDK17  → jdk.version=17

# Composite: All-Java-Tests
# Snapshot deps on: Compile, Test-JDK8, Test-JDK11, Test-JDK17

Pattern: test against multiple OS

# Similar approach with agent requirements on OS:
# Test-Linux   → agent requirement: teamcity.agent.os.name=Linux
# Test-Windows → agent requirement: teamcity.agent.os.name=Windows

TeamCity 2017.2 doesn't have native "if/else" step conditions based on parameter values. Use these patterns instead:

Pattern 1: Shell conditional in Command Line step

#!/bin/bash
# Only deploy if on main branch
if [ "%teamcity.build.branch%" = "refs/heads/main" ]; then
  echo "Main branch — deploying..."
  ./deploy.sh --env=staging
else
  echo "Feature branch — skipping deploy"
fi

Pattern 2: Separate build configs per scenario

# Instead of conditional steps, use build chain:
# BuildAndTest → runs on all branches
# Deploy       → runs only on main (trigger with branch filter: +refs/heads/main)

# VCS trigger on Deploy config:
# Branch filter: +refs/heads/main (only triggers on main)

Pattern 3: Parameter-driven skip

#!/bin/bash
# Check if skip flag is set
if [ "%run.integration.tests%" = "false" ]; then
  echo "##teamcity[buildStatus status='SUCCESS' text='Integration tests skipped']"
  exit 0
fi

# Run integration tests
mvn verify -P integration

Without clean-up policies, the TeamCity data directory grows indefinitely. Set policies at server and project levels.

Server-level clean-up

Administration → Server Administration → Clean-up Settings:

• Run clean-up at: 02:00 daily (avoid peak hours)
• Maximum duration: 60 minutes

Project-level clean-up rules

Administration → <Project> → Clean-up Rules → Add rule:

# Recommended rules for an active service build config:
# Keep: last 30 builds (full history including logs + artifacts)
# Keep: last 100 builds (history only, no artifacts)
# Keep: pinned builds indefinitely (don't delete release builds)

# This keeps recent builds with artifacts for debugging,
# and longer history for trend analysis, without infinite disk growth.

Creating a backup

1. Go to Administration → Server Administration → Backup.
2. Select what to include: configuration, database, build logs, artifacts. For a minimal config backup: include configuration + database only.
3. Click Start Backup. The backup ZIP is created in <Data Dir>/backup/.

Scheduled backups

TeamCity can create backups on a schedule. Enable in Administration → Backup → Enable scheduled backups. Set time and what to include. Copy backup ZIPs to off-server storage (S3, NFS).

Restore procedure

# 1. Stop the TeamCity server
systemctl stop teamcity

# 2. Run maintainDB restore tool
cd /opt/teamcity/bin
./maintainDB.sh restore \
  -F /var/lib/teamcity/backup/TeamCity_Backup_20260612_0200.zip \
  -T /var/lib/teamcity   # data directory

# 3. Start the server
systemctl start teamcity

# The maintainDB tool restores: database schema, data, and config files

# TeamCity server JVM settings
# Linux: /opt/teamcity/bin/teamcity-server.sh
# Windows: set TEAMCITY_SERVER_OPTS in registry or service wrapper

export TEAMCITY_SERVER_MEM_OPTS="\
  -Xms1g \
  -Xmx8g \
  -XX:MaxMetaspaceSize=512m \
  -XX:+UseG1GC \
  -XX:MaxGCPauseMillis=200 \
  -XX:G1HeapRegionSize=16m \
  -XX:InitiatingHeapOccupancyPercent=45"

# TeamCity agent JVM settings
# conf/buildAgent.properties:
# JAVA_OPTS=-Xmx512m

# Monitoring GC:
# Add to server opts: -Xloggc:/var/log/teamcity-gc.log -XX:+PrintGCDateStamps

Run TeamCity agents inside Docker containers for isolated, disposable build environments.

# Pull official TeamCity agent image
docker pull jetbrains/teamcity-agent:2017.2.2

# Run a TeamCity agent container
docker run -d \
  --name tc-agent-1 \
  -e SERVER_URL="http://YOUR_TC_SERVER:8111" \
  -e AGENT_NAME="Docker-Agent-01" \
  -v tc-agent-1-work:/opt/buildagent/work \
  -v tc-agent-1-system:/opt/buildagent/system \
  jetbrains/teamcity-agent:2017.2.2

Docker agent with Docker-in-Docker

# Mount the host Docker socket for Docker builds inside the agent
docker run -d \
  --name tc-agent-docker \
  -e SERVER_URL="http://YOUR_TC_SERVER:8111" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v tc-agent-docker-work:/opt/buildagent/work \
  --privileged \
  jetbrains/teamcity-agent:2017.2.2

A complete Kotlin DSL example for a project with one build configuration, demonstrating the key DSL elements:

// .teamcity/settings.kts
import jetbrains.buildServer.configs.kotlin.v2019_2.*
import jetbrains.buildServer.configs.kotlin.v2019_2.buildFeatures.commitStatusPublisher
import jetbrains.buildServer.configs.kotlin.v2019_2.buildSteps.maven
import jetbrains.buildServer.configs.kotlin.v2019_2.triggers.vcs
import jetbrains.buildServer.configs.kotlin.v2019_2.vcs.GitVcsRoot

version = "2017.2"

project {
  vcsRoot(MyGitHubRepo)
  buildType(Build)
}

object MyGitHubRepo : GitVcsRoot({
  name = "GitHub — myorg/user-service"
  url = "https://github.com/myorg/user-service.git"
  branch = "refs/heads/main"
  branchSpec = "+:refs/heads/*\n+:refs/pull/*/head"
  authMethod = password {
    userName = "myorg-ci-bot"
    password = "credentialsJSON:token-id"   // stored in TeamCity credentials store
  }
})

object Build : BuildType({
  name = "Build"
  vcs { root(MyGitHubRepo) }

  artifactRules = "target/user-service-*.jar => artifacts"

  steps {
    maven {
      name = "Compile and Test"
      goals = "clean verify"
      mavenVersion = defaultProvidedVersion()
      jvmArgs = "-Xmx512m"
    }
  }

  triggers {
    vcs {
      branchFilter = "+:refs/heads/*\n+:refs/pull/*/head"
      quietPeriodMode = USE_DEFAULT
    }
  }

  features {
    commitStatusPublisher {
      publisher = github {
        githubUrl = "https://api.github.com"
        authType = personalToken {
          token = "credentialsJSON:github-status-token"
        }
      }
    }
  }

  failureConditions {
    executionTimeoutMin = 30
    testFailure(true)
  }
})

In-place upgrade procedure for TeamCity 2017.2.2 to a newer version:

1. Take a full backup (Section 15.5) — this is your rollback plan.
2. Read the upgrade notes for your target version in the JetBrains documentation — some upgrades require manual steps.
3. Download the new TeamCity distribution.
4. Stop the TeamCity server: systemctl stop teamcity
5. Run the new installer or extract the tar.gz over the existing installation.
6. Start the server: systemctl start teamcity
7. TeamCity automatically runs the database migration on first start. This may take several minutes.
8. Verify: open the UI, check Administration → Server Info for the new version number.
9. Agents auto-upgrade to the new version within 5–10 minutes.

TeamCity 2017.2 does not support multi-server active-active clustering. A single server is the only supported architecture. For high availability:

• Database HA: use MySQL/PostgreSQL with replication. If the TC server machine fails, point a new server at the same database + data directory.
• Data directory on shared storage: NFS or SAN mount so a replacement server can access existing artifacts and config.
• VM snapshots: take nightly VM snapshots of the TC server machine — fast rollback in 15–30 minutes.
• Multi-node clustering: available in TeamCity 2018.2+. If you need active-active HA, upgrade to a newer TeamCity version.

Combining everything in this guide into a complete production build configuration set for a Java Spring Boot microservice: