Configure Server Installation

Changing Server Port

If another application uses the same port as the TeamCity server, the server won't be able to start. This will result in "Address already in use" errors in the server logs or server console.

If you install a server from .exe, you can customize the port in the installation wizard.

To change the port of the installed/unpacked server, open the <TeamCity Home Directory>/conf/server.xml file and set another number in the not commented <Connector> XML node:

<Connector port="8111" ...

To apply the changes, restart the server by.

If you change the port of an operational TeamCity server, you also need to change it in all the stored URLs of the server (browser bookmarks, agents' serverUrl properties, URL in users' IDEs, the Server URL setting on the Administration | Global Settings page).
If you run another Tomcat server on the same machine, you might also need to change other service ports of the Tomcat server (search for port= in the server.xml file).

If you want to use the HTTPS protocol, it should be enabled separately. The process is specific to the web server used (by default, Tomcat). See notes on how to configure HTTPS for TeamCity web UI.

Changing Server Context

By default, the TeamCity server is accessible under the root context of the server address (for example, http://localhost:8111/). To make it available under a nested path instead (for example, http://localhost:8111/teamcity/), you need to:

Stop the TeamCity server.
Rename the <TeamCity Home Directory>\webapps\ROOT directory to <TeamCity Home Directory>\webapps\teamcity.
Start the TeamCity server.

Configure Memory Settings for TeamCity Server

TeamCity Server has the main process which can also launch child processes. Child processes use available memory on the machine. This section covers the memory settings of the main TeamCity server process only, as it requires special configuration.

As a JVM application, the TeamCity main server process utilizes only memory available to the JVM. The required memory depends on the JVM bitness (64- or 32-bit). The memory used by JVM usually consists of: heap (configured via -Xmx) and metaspace (limited by the amount of available native memory), internal JVM (usually tens of MB), and OS-dependent memory features like memory-mapped files. TeamCity mostly depends on the heap memory. This setting can be manually configured by passing the -Xmx (heap space) option to the JVM running the TeamCity server. In most cases, it means setting TEAMCITY_SERVER_MEM_OPTS environment variable to a value like -Xmx750m. To apply the changed memory value, stop and then start the server process via the respective commands.

Once you start using TeamCity for production purposes or if you want to load the server during evaluation, you should manually set the appropriate memory settings for the TeamCity server.

Possible values:

Minimum setting: for 64-bit Java (bundled) -Xmx1024m, for 32-bit Java -Xmx750m.
Recommended setting for medium server: for 64-bit Java -Xmx2048m, for 32-bit Java -Xmx1024m. Greater settings with the 32-bit Java can cause OutOfMemoryError with "Native memory allocation (malloc) failed" JVM crashes or "Unable to create new native thread" messages.
Recommended setting for large server (64-bit Java should be used): -Xmx4g. This setting should be suitable for an installation with up to two hundreds of agents and thousands of build configurations. Custom plugins might require increasing the value defined via the Xmx parameter.
Maximum setting for large-scale server (64-bit Java should be used): -Xmx10g. Greater values can be used for larger TeamCity installations. However, generally it is not recommended to use values greater than 10g without consulting TeamCity support.

The ReservedCodeCacheSize=640m attribute is set by default for new server installations. If the attribute was specified before TeamCity 2022.04.4, you'll have to update it manually after upgrading.

If an OutOfMemory error occurs or you consistently see a memory-related warning in the TeamCity UI, it means you need to increase the setting to the next level.

Tips:

A rule of thumb is that the 64-bit JVM should be assigned twice as much memory as the 32-bit for the same application. If you switch to the 64-bit JVM (for example, on upgrading TeamCity), make sure to adjust the memory setting (-Xmx) accordingly. It does not make sense to switch to 64-bit if you dedicate less than the double amount of memory to the application.
Large TeamCity installations might benefit from fine-tuning of the memory settings. The amount of memory dedicated to the TeamCity server JVM should not regularly exceed 60% of the total available physical memory on the machine (to allow for nested process and OS-level caches usage). Also, with heaps (–Xmx) set to more than 8 GB, if the machine has many CPU cores (for example, more than 8) and current CPU usage is below 60%, enabling G1 JVM garbage collector via the -XX:+UseG1GC JVM option might reduce the length of stop-the-world GC pauses.
The recommended approach is to start with the default settings and monitor the used memory on the Administration | Diagnostics page. If the server uses more than 80% of memory consistently without drops for tens of minutes, that is probably a signal to increase the -Xmx memory value by another 20%.

Configure TeamCity Data Directory

The default placement of the TeamCity Data Directory can be changed. See this article for details.

Configuring Server for Production Use

An out-of-the-box TeamCity server installation is suitable for evaluation purposes. For production use, you will need to perform additional configuration. It typically includes these steps:

Check that the server is using a proper server port and configure access via HTTPS.
Make sure the TeamCity server URL and email server settings are correct.
Configure the server process for OS-dependent autostart on machine reboot.
Use a reliable storage for TeamCity Data Directory.
Use an external database.
Configure recommended memory settings. Use "maximum settings" for active or growing servers.
Plan for regular backups.
Plan for regular upgrades to the latest TeamCity releases.
Consider adding the teamcity.installation.completed=true line into the <TeamCity Data Directory>\conf\teamcity-startup.properties file — this will prevent the server from creating an administrator user if no such user is found.
Make sure to read the notes on configuring the server for performance and security notes.

Last modified: 04 April 2024