Set up a TeamCity test server from a production copy: isolate it from production – Support | JetBrains

Background

A TeamCity test or staging server is almost always a copy of a production server: the same projects, build configurations, database, and Data Directory. A direct copy keeps every external connection of the original active. Without isolation, the copy will:

send build notifications to real users;
publish commit statuses to the real VCS;
start real cloud agents;
run deploy builds against production targets;
clean up artifacts from external storage (S3, Docker Registry) that production still uses.

The steps below block each of those behaviors before the copy starts. It covers the standard, bundled TeamCity features. A specific installation can add custom build scripts, plugins, or external systems that call the TeamCity API; review those for the same isolation.

Question

How can a TeamCity test or staging server be created from a copy of a production server without affecting production systems, users, or external integrations?

Answer

1. Create the copy

Create the copy with the built-in backup or manually. The manual approach suits a complete move; backup and restore suits a throwaway test server. See Create a Copy of TeamCity Server with All Data.

Back up production from Administration | Backup, or stop the server and copy the Data Directory and database.
Install a new TeamCity server of the same version as production.
Restore the backup, or point the new install at the copied data.

The staging server must have its own Data Directory, its own database (a separate schema or server), and its own artifact directory. A staging server that shares a database or artifact storage with production will corrupt or delete production data during cleanup and builds.

2. Apply the license

A single TeamCity license cannot run on two live servers at the same time. A standby copy that never runs at the same time as production can reuse the same license. A test copy that runs alongside production needs its own license. A one-time, time-limited trial license is available from the TeamCity download page; for an extension, contact JetBrains sales. See the Licensing Policy.

3. Isolate the copy before the first start

Apply all of the following before the staging server starts for the first time.

Set the server identity and URL

Both values are attributes of the root XML element in <TeamCity Data Directory>/config/main-config.xml. Remove the uuid attribute so the copy receives a new unique server ID instead of reusing the production server's ID. Set the rootURL attribute to the staging address; this is the same value as the Server URL field on Administration | Global Settings.

Disable cleanup

Cleanup on the copy may delete files from external storage that production still uses. In <TeamCity Data Directory>/config/main-config.xml, change:

<db-compact enabled="true">

to:

<db-compact enabled="false">

Disable cloud integrations

A test server must not start new cloud agents. In <TeamCity Data Directory>/config/internal.properties (create the file if it does not exist), add:

teamcity.cloud.integration.enabled=false

Disable plugins that write to external systems

Create <TeamCity Data Directory>/config/disabled-plugins.xml with the following content:

<?xml version="1.0" encoding="UTF-8"?>
<disabled-plugins>
  <disabled-plugin name="commit-status-publisher" />
  <disabled-plugin name="slackNotifier" />
  <disabled-plugin name="email" />
  <disabled-plugin name="webhooks" />
  <disabled-plugin name="searchBuildByNumber" />
</disabled-plugins>

Add any third-party plugins that push data to systems shared with production.

Email verification

Email verification is off by default, and disabling the email plugin above already stops the copy from sending mail, including verification messages. In most cases no further action is needed. If production had email verification enabled and the setting must be off before the first start, it is stored in <TeamCity Data Directory>/config/auth-config.xml. TeamCity supports editing that file before the server starts; it is the same file the Administration | Authentication page writes to.

Disable versioned settings

Prevent the copy from committing its converted settings back to the VCS. Add this property to the same internal.properties file:

teamcity.versionedSettings.enabled=false

Start with the build queue paused

Pausing the queue after start leaves a window in which triggers can launch builds. Starting with the queue already paused removes that window. The paused state is stored in <TeamCity Data Directory>/config/plugin.queue-pauser.xml, the same file TeamCity writes when the queue is paused from the UI. Create it before the first start with queue-enabled set to false:

<?xml version="1.0" encoding="UTF-8"?>
<settings>
  <param name="queue-enabled" value="false" />
  <param name="state-changed-reason" value="" />
  <param name="state-changed-actor" value="USER" />
  <param name="state-changed-by" value="1" />
  <param name="state-changed-on" value="1662042549840" />
</settings>

Only queue-enabled="false" is required; the state-changed-* parameters are metadata. Unpause the queue from the web UI after the checks are complete. This file is an internal TeamCity implementation detail rather than a documented setting, so its format can change between versions.

4. After the server starts

Stop automatic triggers. Open the top-level (Root) project's Project Settings, choose Actions | Pause/Activate, select the box next to the project to pause all its build configurations, and click Apply. Check Cancel already queued builds if build configuration is paused to clear builds a trigger already enqueued.
Confirm no build deploys to production, including Maven builds that publish to non-local repositories.
Increase the VCS checking-for-changes interval (the server-wide default and any per-VCS-root overrides), or adjust the VCS roots so they do not contact production systems.
Attach a dedicated staging agent configured with the new Server URL. Do not let production agents register with the staging server.

The paused queue stays as a backstop: a paused configuration blocks only automatic triggers, so manual runs and build-chain dependencies can still start, and a configuration added after the pause starts active. When the checks are complete, activate the build configurations (same dialog, clear the box) and unpause the build queue.

Checklist

Before the first start:

Separate Data Directory, database, and artifact directory
uuid removed and rootURL set in main-config.xml
Own or trial license in place
Cleanup disabled (<db-compact enabled="false">)
Cloud integrations disabled (teamcity.cloud.integration.enabled=false)
disabled-plugins.xml created
Email verification handled (off by default; email plugin disabled)
Versioned settings disabled (teamcity.versionedSettings.enabled=false)
Build queue paused (plugin.queue-pauser.xml)

After the first start:

Root project paused, then queue unpaused when ready
No production-deploying builds enabled
VCS polling interval increased
Dedicated staging agent connected

References