TeamCity CI: Getting Started

By Khimananda Oli | Last reviewed: August 2026

Setting up a reliable continuous integration server remains a foundational step for any engineering team moving beyond manual deployments. TeamCity CI: Getting Started requires understanding both the central server architecture and the distributed build agent model that powers it. Unlike simpler SaaS options, self-hosted TeamCity gives you full control over infrastructure, secrets, and network isolation, but demands correct initial configuration to avoid scaling bottlenecks later. This guide walks through the production-grade setup I use when helping teams establish compliant, auditable CI environments.

How do you install and configure the TeamCity CI server for production?

The most common mistake during TeamCity CI: Getting Started is using the default HSQLDB file database. This works for evaluation but corrupts under concurrent load or unexpected shutdowns. For any environment that matters, provision an external PostgreSQL instance first. If you are also evaluating infrastructure automation, my guide on infrastructure as code with Terraform covers provisioning this database reproducibly.

Database and server initialization

1. Create a dedicated PostgreSQL database and user with restricted privileges. Never reuse the postgres superuser.
2. Download the latest TeamCity Linux distribution (2024.x or newer for current LTS support) and extract to /opt/teamcity.
3. Edit /opt/teamcity/conf/database.properties to point to your external Postgres instance, specifying the JDBC URL, username, and password.
4. Start the server using the bundled bin/teamcity-server.sh start script or, preferably, create a systemd unit file for automatic restarts and log management.
5. Complete the web wizard at http://localhost:8111, creating the initial admin account and accepting the license agreement.

<!-- Example systemd unit snippet for TeamCity server -->
[Unit]
Description=TeamCity CI Server
After=network.target postgresql.service

[Service]
Type=forking
User=teamcity
Environment="TEAMCITY_SERVER_OPTS=-Dteamcity.server.root.url=https://ci.yourdomain.com"
ExecStart=/opt/teamcity/bin/teamcity-server.sh start
ExecStop=/opt/teamcity/bin/teamcity-server.sh stop
PIDFile=/opt/teamcity/logs/teamcity.pid

[Install]
WantedBy=multi-user.target

Always set teamcity.server.root.url explicitly. Without it, webhook notifications, email links, and agent authorization tokens may resolve to localhost or internal IPs, breaking integrations silently.

How do you set up and authorize TeamCity build agents securely?

Build agents execute your code and have access to secrets, source repositories, and deployment targets. Treat them as untrusted by default until authorized. During TeamCity CI: Getting Started, many teams skip agent hardening and later face credential leaks or supply chain risks.

Agent installation and registration

• Install the agent on a separate host or container from the server. Co-location creates resource contention and expands the blast radius of compromises.
• Configure buildAgent.properties with the server URL and a unique agent name. Do not pre-authorize agents in the UI before verifying their identity.
• Start the agent service. It will appear in the "Unauthorized Agents" tab in the TeamCity web interface.
• Review the agent's system information (OS, installed tools, IP address) before clicking "Authorize". Verify it matches expected infrastructure.

In regulated environments, I require agents to run inside ephemeral containers or VMs that reset after each build. Persistent agents accumulate state, cached credentials, and temporary files that become attack vectors. If you are containerizing workloads, the principles in Docker for beginners apply directly to agent isolation.

How do you create your first TeamCity build configuration correctly?

A build configuration defines what gets built, how, and when. Avoid the temptation to use auto-detection wizards for production pipelines. They generate opaque configurations that fail unpredictably during audits or migrations. Define everything explicitly.

VCS roots and build steps

Create a VCS root pointing to your Git repository. Use SSH keys stored in TeamCity's credential store rather than embedding tokens in URLs. Set the checkout directory to a clean workspace path and enable "Clean all files before build" to prevent artifact leakage between runs.

# Example Kotlin DSL snippet for a Laravel test build
object Build : BuildType({
    name = "Laravel Test Suite"
    
    vcs {
        root(DslContext.settingsRoot)
        cleanCheckout = true
    }
    
    steps {
        script {
            name = "Install Dependencies"
            scriptContent = "composer install --no-interaction --prefer-dist"
        }
        script {
            name = "Run PHPUnit"
            scriptContent = "./vendor/bin/phpunit --coverage-clover coverage.xml"
        }
    }
    
    artifactRules = "+:coverage.xml => reports/"
})

Define artifact rules explicitly. Without them, test reports, compiled binaries, and logs disappear after the build finishes, making debugging impossible. Store only what downstream stages or humans actually need.

How does TeamCity CI compare to Jenkins and GitLab CI in 2026?

Choosing a CI platform depends on team size, compliance requirements, and existing toolchain investment. The table below reflects real trade-offs I evaluate when consulting for teams across Nepal and globally. If you are still deciding between platforms, my comparison of GitHub Actions vs GitLab CI provides additional context for SaaS-first teams.

TeamCity wins for teams needing strong audit trails, complex multi-stage pipelines, and air-gapped deployments. Jenkins remains viable only if you already have deep institutional knowledge and cannot migrate. GitLab CI suits teams fully committed to the GitLab ecosystem with simpler workflows.

What security and compliance practices matter during TeamCity CI setup?

CI servers are high-value targets. They hold deployment credentials, access source code, and execute arbitrary commands. During TeamCity CI: Getting Started, bake in these controls from day one rather than retrofitting them before an audit.

• Enforce HTTPS everywhere. Redirect HTTP to HTTPS at the reverse proxy level. Never expose port 8111 directly to untrusted networks.
• Use parameterized secrets. Store passwords, API keys, and tokens in TeamCity's built-in secret parameters or integrate with HashiCorp Vault. Never hardcode credentials in build scripts or VCS.
• Restrict agent capabilities. Assign specific toolchains and permissions per agent pool. A frontend build agent should not have AWS CLI access or database credentials.
• Enable audit logging. TeamCity logs all configuration changes, user actions, and build triggers by default. Retain these logs externally for compliance evidence. For broader observability patterns, see monitoring with Prometheus and Grafana.
• Implement RBAC early. Create roles for developers, reviewers, and administrators. Grant minimum necessary permissions. Audit role assignments quarterly.

For teams pursuing SOC 2 or ISO 27001, document your CI/CD change management process alongside the technical setup. Auditors care as much about who can modify pipelines and how changes are approved as they do about encryption at rest.

Next Steps After TeamCity CI Getting Started

You now have a functional, secure foundation for TeamCity CI: Getting Started. The next phase is converting manual build steps into reproducible Kotlin DSL configurations, setting up build chains for parallel testing, and integrating artifact storage with your deployment pipeline. Monitor build queue times and agent utilization weekly; scaling bottlenecks appear fast once adoption grows. If your team needs help designing compliant CI architectures, migrating from legacy Jenkins instances, or optimizing build performance, reach out to discuss your specific requirements.