Installation & Initial Setup

# Start server
net start TCBuildAgent
net start TeamCityServer

# Or use the launcher scripts
C:\TeamCity\bin\teamcity-server.bat start
C:\TeamCity\bin\teamcity-agent.bat start

# 1. Ensure Java 8 is installed
java -version   # must show 1.8.x

# 2. Download TeamCity tar.gz
wget https://download.jetbrains.com/teamcity/TeamCity-2017.2.2.tar.gz

# 3. Extract to /opt
sudo tar -xzf TeamCity-2017.2.2.tar.gz -C /opt
sudo mv /opt/TeamCity /opt/teamcity

# 4. Create dedicated user (never run as root)
sudo useradd -m -d /home/teamcity -s /bin/bash teamcity
sudo chown -R teamcity:teamcity /opt/teamcity

# 5. Set data directory (optional — default is ~/.BuildServer)
echo "TEAMCITY_DATA_PATH=/var/lib/teamcity" | sudo tee /opt/teamcity/conf/teamcity-startup.properties

# 6. Start the server
sudo -u teamcity /opt/teamcity/bin/teamcity-server.sh start

# 7. Start the bundled agent
sudo -u teamcity /opt/teamcity/buildAgent/bin/agent.sh start

systemd service (recommended)

# /etc/systemd/system/teamcity.service
[Unit]
Description=TeamCity Build Server
After=network.target

[Service]
Type=forking
User=teamcity
ExecStart=/opt/teamcity/bin/teamcity-server.sh start
ExecStop=/opt/teamcity/bin/teamcity-server.sh stop
PIDFile=/opt/teamcity/logs/teamcity.pid
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable teamcity
sudo systemctl start teamcity
sudo systemctl status teamcity

The first time you open TeamCity in a browser (http://server:8111), the setup wizard runs. It has three steps:

After the wizard you land on the Projects page. The server is running. The bundled build agent should auto-connect within 1–2 minutes and appear under Agents → All Agents as "Unauthorized" — you must manually authorize it (see Phase 6).

MySQL setup

-- Create database and user (MySQL 5.6+)
CREATE DATABASE teamcity CHARACTER SET utf8 COLLATE utf8_bin;
CREATE USER 'teamcity'@'localhost' IDENTIFIED BY 'StrongPass123!';
GRANT ALL PRIVILEGES ON teamcity.* TO 'teamcity'@'localhost';
FLUSH PRIVILEGES;

Download the MySQL JDBC driver (mysql-connector-java-5.1.xx.jar) and place it in:

<TeamCity Data Dir>/lib/jdbc/mysql-connector-java-5.1.xx.jar

In the setup wizard, select MySQL and enter:

• Database host: localhost (or remote host)
• Database name: teamcity
• Username: teamcity
• Password: StrongPass123!

PostgreSQL setup

-- PostgreSQL 9.4+
CREATE DATABASE teamcity ENCODING 'UTF8';
CREATE USER teamcity WITH ENCRYPTED PASSWORD 'StrongPass123!';
GRANT ALL PRIVILEGES ON DATABASE teamcity TO teamcity;

Download the PostgreSQL JDBC driver (postgresql-42.x.x.jar) and place it in <Data Dir>/lib/jdbc/.

.BuildServer/            <-- TeamCity Data Directory root
├── config/              <-- Project + build config XML files
│   ├── projects/
│   │   └── _Root/       <-- Root project settings
│   └── database.properties
├── system/
│   ├── artifacts/       <-- Published build artifacts
│   │   └── ProjectName/
│   │       └── BuildConfigName/
│   ├── caches/          <-- VCS fetch caches, checkout caches
│   └── buildserver.db   <-- HSQL data file (if using HSQL)
├── plugins/             <-- Installed .zip plugins
├── lib/
│   └── jdbc/            <-- Database driver JAR goes here
└── logs/                <-- teamcity-server.log, catalina.out

The bundled agent is installed alongside the server but must be authorized before it can run builds. For a remote agent (separate machine):

# On the agent machine — download agent installer from server
wget http://YOUR_TC_SERVER:8111/update/buildAgent.zip
unzip buildAgent.zip -d /opt/buildagent

# Configure the agent to connect to the server
cat > /opt/buildagent/conf/buildAgent.properties << 'EOF'
serverUrl=http://YOUR_TC_SERVER:8111
name=Agent-Linux-01
workDir=../work
tempDir=../temp
EOF

# Start the agent
/opt/buildagent/bin/agent.sh start

Authorizing the agent

After the agent starts, it appears in Agents → Unauthorized Agents in the TeamCity UI. Click Authorize. The agent is now ready to accept builds.

HTTPS with a reverse proxy (nginx)

# /etc/nginx/sites-available/teamcity
server {
    listen 443 ssl;
    server_name ci.yourcompany.com;

    ssl_certificate     /etc/ssl/certs/yourcompany.crt;
    ssl_certificate_key /etc/ssl/private/yourcompany.key;

    location / {
        proxy_pass         http://localhost:8111;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection "upgrade";
        proxy_set_header   Host $host;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
        proxy_read_timeout 600;
        proxy_connect_timeout 600;
        proxy_send_timeout 600;
    }
}

# Redirect HTTP to HTTPS
server {
    listen 80;
    server_name ci.yourcompany.com;
    return 301 https://$host$request_uri;
}

Tell TeamCity about the public HTTPS URL: Administration → Server Administration → Server URL → set to https://ci.yourcompany.com. This ensures links in emails and commit statuses use the correct URL.

Email server (for notifications)

Go to Administration → Email Notifier. Enter your SMTP server details. Click Test connection before saving. Without this, build failure emails won't work.

Server memory tuning

# <TeamCity>/bin/teamcity-server.sh — set JVM heap
export TEAMCITY_SERVER_MEM_OPTS="-Xms1g -Xmx4g -XX:MaxPermSize=270m"

# For Java 8, also add:
# -XX:+UseG1GC -XX:MaxGCPauseMillis=200