TeamCity On-Premises 2023.11 Help

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:

  1. Stop the TeamCity server.

  2. Rename the <TeamCity Home Directory>\webapps\ROOT directory to <TeamCity Home Directory>\webapps\teamcity.

  3. 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.

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:

Last modified: 25 October 2022