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:
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
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.
<TeamCity Home Directory>\webapps\ROOTdirectory to
<TeamCity Home Directory>\webapps\teamcity.
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.
Minimum setting: for 64-bit Java (bundled)
-Xmx1024m, for 32-bit Java
Recommended setting for medium server: for 64-bit Java
-Xmx2048m, for 32-bit Java
-Xmx1024m. Greater settings with the 32-bit Java can cause
OutOfMemoryErrorwith "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
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
10gwithout consulting TeamCity support.
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.
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:
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=trueline into the
<TeamCity Data Directory>\conf\teamcity-startup.propertiesfile — 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.