- Review software requirements and hardware requirements notes and platform selection
- Review TeamCity Licensing Policy
- Install and configure the TeamCity server per instructions below
After you selected one of the the TeamCity installation options, proceed with corresponding installation instructions:
- Windows .exe distribution - the executable which provides the installation wizard for Windows platforms and allows installing the server as a Windows service;
- .tar.gz distribution - the archive with a "portable" version suitable for all platforms;
- Docker image - check the instructions at the image page;
- .war distribution - for experienced users who want to run TeamCity in a separately installed Web application server. Please consider using .tar.gz distribution instead. .war is not recommended to use unless really required (please let us know the reasons).
- include a Tomcat version which TeamCity is tested with, so it is known to be a working combination. This might not be the case with an external Tomcat.
- define additional JRE options which are usually recommended for running the server
- have the teamcity-server startup script which provides several convenience options (e.g. separate environment variable for memory settings) and configures TeamCity correctly (e.g. log4j configuration)
- (at least under Windows) provide better error reporting for some cases (like a missing Java installation)
- under Windows, allow running TeamCity as a service with the ability to use the same configuration as if run from the console
- come bundled with a build agent distribution and single startup script which allows for easy TeamCity server evaluation with one agent
- come bundled with the devPackage for TeamCity plugin development.
- may provide more convenience features in the future
If you cannot access the TeamCity web UI after successful installation, please refer to the #Troubleshooting TeamCity Installation Issues section.
The build server and one build agent will be installed by default for Windows, Linux or macOS. If you need more build agents, refer to the Installing Additional Build Agents section.
During the server setup you can select either an internal database or an existing external database. By default, TeamCity uses an HSQLDB database that does not require configuring. This database suites the purposes of testing and evaluating the system.
If you opted to install the services, use the standard Windows
Services applet to manage the service.
Otherwise, use standard scripts.
If you did not change the default port (80) during the installation, the TeamCity web UI can be accessed via http://localhost/ in a web browser running on the same machine where the server is installed. Please note that port 80 can be used by other programs (e.g. Skype, or other web servers like IIS). In this case you can specify another port during the installation and use http://localhost:<port>/ address in the browser.
It is not recommended to use .war distribution. Use the TeamCity .tar.gz distribution (bundled with Tomcat web server) instead. If you have important reasons to deploy TeamCity into existing web server and want to use .war distribution, please let us know the reasons.
- Make sure your web application server is stopped.
- Copy the downloaded
TeamCity<version number>.warfile into the web applications directory of your J2EE container under the
TeamCity.warname (the name of the file is generally used as a part of the URL) or deploy the .war following the documentation of the web server. Please make sure there is no other version of TeamCity deployed (e.g. do not preserve the old TeamCity web application directory under the web server applications directory).
- Ensure the TeamCity web application gets sufficient amount of memory. Please increase the memory accordingly if you have other web applications running in the same JVM.
- If you are deploying TeamCity to the Tomcat container, please add
useBodyEncodingForURI="true"attribute to the main
Connectortag for the server in the
- If you are deploying TeamCity to Jetty container version >7.5.5 (including 8.x.x), please make sure the system property
org.apache.jasper.compiler.disablejsr199is set to
- Ensure that the servlet container is configured to unpack the deployed war files. Though for most servlet containers it is the default behavior, for some it is not (e.g. Jetty version >7.0.2) and should be explicitly configured. TeamCity is not able to work from a packed .war: if started this way, there will be a note on this the logs and UI.
Configure the appropriate TeamCity Data Directory to be used by TeamCity.
Note that it is recommended to start with an empty TeamCity Data Directory. After completing the installation and performing the first TeamCity server start, the required data (e.g. database settings file) can be moved to the directory.
- Check/configure the TeamCity logging properties by specifying the
- Restart the server or deploy the application via the servlet container administration interface and access http://server:port/TeamCity/, where "TeamCity" is the name of the
Typically, you will need to unpack it and make the script perform the steps noted in Configuring Server for Production Use section.
If you want to get a pre-configured server right away, put files from a previously configured server into the Data Directory. For each new server you will need to ensure it points to a new database (configured in <Data Directory>\config\database.properties) and change
<Data Directory>\config\main-config.xml file not to have the "uuid" attribute in the root XML element (so new one can be generated) and setting appropriate value for "rootURL" attribute.
Notes on configuring Windows for the server setup (based on Windows Server 2016): - enable Remote desktop connections - create dedicated user (e.g. "TeamCity") and assign it administrator permissions - disable disk indexing for all disks (or at least for the disks where TeamCity home and TeamCity Data Directory are located) - disable real-time protection и cloud-based protection in Windows Defender - check Windows Firewall is enabled (counter-intuitively this changes Windows network stack behavior to handle more incoming but not yet accepted network connections) on Windows Firewall settings: -- enable incoming connections to TeamCity application ports -- enable ICMP pings -- enable ports for monitoring agent, etc. - (if IPv6 network is not used) disable ipv6 on network adapter settings - disable weekly schedule for fragmentation analyzing - disable "Optimize drive" service - (for manual updates application) set Windows updates policy to "DownloadOnly" via sconfig utility - consider enabling jumbo frames and ensuring that the network supports the setting (check that all the related network infrastructure supports it e.g. via "ping -l 8960 -f <host>")
To use another version of the Tomcat web server instead of the one bundled in the .tar.gz and .exe distributions), you can either use the .war TeamCity distribution (not recommended) or perform the Tomcat upgrade/patch for TeamCity installed from the .exe or .tar.gz distributions.
For the latter, you might want to:
If TeamCity is installed into an existing web server (.war distribution), start the server according to its documentation. Make sure you configure TeamCity-specific logging-related properties and pass suitable memory options.
One of the most common issues with the server installation is using a port that is already used by another program. See below on changing the default port.
The TeamCity server requires JRE 8 to operate, the agent can run with Java 6-10, but Java 8 is recommended. The recommended Java download is AdoptOpenJDK.
It is recommended to use the 32-bit installation unless you need to dedicate more memory to TeamCity server. Please check the 64-bit Java notes before upgrade.
If you configured any native libraries for use with TeamCity (like a .dll for using Microsoft SQL database Integrated Security option), you need to update the libraries to match the JVM x86/x64 platform.
TeamCity server can run under both the 32- and 64-bit JVM.
It is recommended to use the 32-bit JVM unless you need to dedicate more than 1Gb of memory (via -Xmx JVM option) to the TeamCity process (see details) or your database requirements are different.
If you choose to use the 64-bit JVM, note that the memory usage is almost doubled when switching from the 32- to 64-bit JVM, so please make sure you specify at least twice as much memory as for 32-bit JVM, see #Setting Up Memory settings for TeamCity Server.
To update to the 64-bit Java:
- update Java to be used by the server
- set JVM memory options. It is recommended to set the following options for the 64-bit JVM:
Once you start using TeamCity for production purposes or you want to load the server during evaluation, you should manually set the appropriate memory settings for the TeamCity server.
- minimum setting (the 32-bit Java should be used (bundled in .exe distribution)):
recommended setting for medium server use (the 32-bit Java should be used):
-Xmx1024m. Greater settings with the 32-bit Java can cause an OutOfMemoryError with "Native memory allocation (malloc) failed" JVM crashes or "unable to create new native thread" messages
- recommended setting for large server use (64-bit Java should be used):
-Xmx4g -XX:ReservedCodeCacheSize=350m. These settings should be suitable for an installation with up to two hundreds of agents and thousands of build configurations. Custom plugins installed might require increasing the values defined via the Xmx parameter.
- maximum settings for large-scale server use (64-bit Java should be used):
-Xmx10g -XX:ReservedCodeCacheSize=512m.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.
- Make sure server URL, email and (optionally) Jabber server settings are specified and are correct
- Configuring the server process for OS-dependent autostart on machine reboot
- Using reliable storage for TeamCity Data Directory
- Using external database
- Configuring recommended memory settings, use "maximum settings" for active or growing servers
- Planning for regular backups
- Planning for regular upgrades to the latest TeamCity releases
(since TeamCity 10.0.3) Consider adding the
"teamcity.installation.completed=true"line into the
<TeamCity Home Directory
>\conf\teamcity-startup.properties file- this will prevent the server from creating an administrator user if no such user is found
See https://youtrack.jetbrains.com/issue/TW-20027 for details