This page covers a new TeamCity server installation. For upgrade instructions, please refer to Upgrade.
To install a TeamCity server, perform the following:
- Choose the appropriate TeamCity distribution (.exe, .tar.gz or .war) based on the details below
- Download the distribution
- Review software requirements and hardware requirements notes and platform selection
- Review TeamCity Licensing Policy
- Install and configure the TeamCity server per instructions below
This page covers:
- Installing TeamCity Server
- Installation Configuration
- Configuring TeamCity Server
Installing TeamCity Server
After you obtained the TeamCity installation package, 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;
- .war distribution - for experienced users who want to run TeamCity in a separately installed Web application server.
Compared to the .war distribution, the .exe and .tar.gz distributions
- 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
- may provide more convenience features in the future
- come bundled with a build agent distribution which allows for easy TeamCity server evaluation with one agent
- come bundled with devPackage for TeamCity plugin development.
If you cannot access the TeamCity web UI after successful installation, please refer to the #Troubleshooting TeamCity Installation Issues section.
Installing TeamCity via Windows installation package
For the Windows platform, run the executable file and follow the installation instructions. You have options to install the TeamCity web server and one build agent that can be run as a Windows service.
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/" address 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.
Installing TeamCity bundled with Tomcat servlet container (Linux, Mac OS X, Windows)
Review software requirements before the installation.
TeamCity<version number>.tar.gz archive (for example, using the
tar xfz TeamCity<version number>.tar.gz command under Linux, or the WinZip, WinRar or similar utility under Windows).
Please use GNU tar to unpack (for example, Solaris 10 tar is reported to truncate too long file names and may cause a
ClassNotFoundException when using the server after such unpacking. Consider getting GNU tar at Solaris packages or using the
gtar xfz command).
Ensure you have JRE or JDK installed and the JAVA_HOME environment variable is pointing to the Java installation directory. The Oracle Java 1.7 is recommended.
Starting TeamCity server
If TeamCity server is installed as a Windows service, follow the usual procedure of starting and stopping services.
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.
If TeamCity is installed using the .exe or .tar.gz distributions, the TeamCity server can be started and stopped by the scripts provided in the
<TeamCity home>/bin directory.
To start/stop the TeamCity server and one default agent at the same time, use the
To start/stop only the TeamCity server, use the
teamcity-server script and pass the required parameters. Start the script without parameters to see the usage instructions.
runAll.bat startto start the server and the default agent
runAll.bat stopto stop the server and the default agent
By default, TeamCity runs on http://localhost:8111/ and has one registered build agent that runs on the same computer.
See the information below for changing the server port.
If you need to pass special properties to the server, refer to Configuring TeamCity Server Startup Properties.
Installing TeamCity into Existing J2EE Container
If TeamCity is the only application in the server, it is recommended to use the TeamCity distribution bundled with Tomcat web server.
- 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.
- 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
TeamCity J2EE container distribution is tested to work with Tomcat 7 servlet container. (See also Supported Platforms and Environments#The TeamCity Server)
Autostart TeamCity server on Mac OS X
Starting up TeamCity server on Mac is quite similar to starting Tomcat on Mac.
- Install TeamCity and make sure it works if started from the command line, with bin/teamcity-server.sh start. We'll assume that TeamCity is installed in the /Library/TeamCity folder
- Create the /Library/LaunchDaemons/jetbrains.teamcity.server.plist file with the following content:
- Test your file by running launchctl load /Library/LaunchDaemons/jetbrains.teamcity.server.plist . This command should start the TeamCity server (you can see this from logs/teamcity-server.log and in browser).
- If you don't want TeamCity to start under the root permissions, specify the UserName key in the plist file, e.g.:
- That's it. Now TeamCity should autostart when the machine starts.
Using another Version of Tomcat
If you want to use another version of Tomcat web server instead of the bundled one, you have the choices of whether to use the .war TeamCity distribution or perform the Tomcat upgrade/patch for TeamCity installed from the .exe or .tar.gz distributions.
For the latter, you might want to:
- backup the current TeamCity home
- delete/move out the directories from the TeamCity home which are also present in the Tomcat distribution
- unpack the Tomcat distribution into the TeamCity home directory
- copy TeamCity-specific files from the previously backed-up/moved directories to the TeamCity home. Namely:
- files under
binwhich are not present in the Tomcat distribution
- delete the default Tomcat
confdirectory and replace it with the one provided by TeamCity
- delete the default Tomcat
webapps/ROOTdirectory and replace it with the one provided by TeamCity
- files under
Troubleshooting TeamCity Installation
Upon successful installation, the TeamCity server web UI can be accessed via a web browser.
The default address that can be used to access TeamCity from the same machine depends on the installation package and installation options. (Port 80 is used for Windows installation, unless another port is specified, port 8111 for .tar.gz installation unless not changed in the server configuration).
If the TeamCity web UI cannot be accessed, please check:
- the "TeamCity Server" service is running (if you installed TeamCity as a Windows service);
- the TeamCity server process (Tomcat) is running (it is a
javaprocess run in the
- the console output if you run the server from a console,
teamcity-server.logand other files in the
<TeamCity home>\logsdirectory for error messages.
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.
Changing Server Port
If you use the TeamCity server Windows installer, you can set the port to be used during installation.
If you use the .war distribution, refer to the manual of the application server used.
Use the following instructions to change the port if you use the .tar.gz distribution.
If another application uses the same port as the TeamCity server, the TeamCity server (Tomcat server) won't start and this will be identified by "Address already in use" errors in the server logs or server console.
To change the server port, in the
>/conf/server.xml file, change the port number in the HTTP/1.1 connector (here the port number is 8111):
To apply the changes, restart the server.
If you run another Tomcat server on the same machine, you might need to also change other Tomcat server service ports (search for "port=" in the server.xml file).
If you want to use the https:// protocol, it should be enabled separately and the process is not specific to TeamCity, but rather for the web server used (Tomcat by default). See also Using HTTPS to access TeamCity server
The TeamCity server is a web application that runs in an J2EE application server (a JVM application). TeamCity server requires a Java SE JRE installation to run.
TeamCity (both server and agent) requires JRE 1.6 (or later) to operate. Using latest Oracle Server JRE 1.7 is recommended (download page). It is recommended to use 32 bit installation unless you need to dedicate more memory to TeamCity server. Please check 64 bit Java notes before upgrade.
For TeamCity agent Java requirements, check Setting up and Running Additional Build Agents#Configuring Java.
The necessary steps to update the Java installation depend on the distribution used.
- if your TeamCity installation has a bundled JRE (there is the
<TeamCity home>\jredirectory), update it by installing a newer JRE per installation instructions and copying the content of the resulting directory to replace the content of the existing
<TeamCity home>\jredirectory. If you also run a TeamCity agent from the
<TeamCity home>\buildAgentdirectory, use the JVM installation instead of JRE.
- if there is no
<TeamCity home>\jredirectory present, set
JAVA_HOMEenvironment variables to be available for the process launching the TeamCity server (setting global OS environment variables and system restart is recommended). The variables should point to the home directory of the installed JRE or JVM (Java SDK) respectively.
- if you use the
.wardistribution, Java update depends on the application server used. Please refer to the manual of your application server.
Using 64 bit Java to Run TeamCity Server
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 1.2Gb 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:
-Xmx4g -XX:MaxPermSize=270m -XX:ReservedCodeCacheSize=350m
Setting Up Memory settings for TeamCity Server
As a JVM application, TeamCity only utilizes memory devoted to the JVM. Memory used by JVM usually consists of: heap (configured via
-Xmx), permgen (configured via
-XX:MaxPermSize), internal JVM (usually tens of Mb), and OS-dependent memory features like memory-mapped files. TeamCity mostly depends on the heap and permgen memory and these settings can be configured for the TeamCity application manually by passing
-Xmx (heap space) and
-XX:MaxPermSize (PermGen space) options to the JVM running the TeamCity server.
- For initial use of TeamCity for production purposes (assuming 32 bit JVM), the minimum recommended settings are:
-Xmx750m -XX:MaxPermSize=270m. If slowness or OutOfMemory error occurs, please increase the settings to
-Xmx1200m -XX:MaxPermSize=270m. Do not set more for
-Xmx1200msetting in 32 bit mode as that can cause "Native memory allocation (malloc) failed" JVM crashes or "unable to create new native thread" OutOfMemoryError.
- The maximum settings that you might ever need are (x64 JVM should be used):
-Xmx4g -XX:MaxPermSize=270m. These settings will be suitable for an installation with more than a hundred of agents and thousands of build configurations and without custom plugins installed.
- If you run TeamCity via the
teamcity-serverscripts or via a Windows service installed, the default settings used are: 512 Mb for the heap and 150 Mb for the PermGen.
To change the memory settings, refer to Configuring TeamCity Server Startup Properties, or to the documentation of your application server, if you run TeamCity using the .war distribution.
Generally this means setting
TEAMCITY_SERVER_MEM_OPTS environment variable to the value like
- 32 bit JVM can use up to 1.2Gb heap memory (-Xmx1200m). If more memory is necessary, 64 bit JVM should be used assigning not less than 2.5Gb (-Xmx2500m). It's highly unlikely that you will need to dedicate more than 4Gb of memory to the TeamCity process.
- A rule of thumb is that 64 bit JVM should be assigned twice as much memory as 32 bit for the same application. If you switch to 64 bit JVM please make sure you adjust the memory settings (both
-XX:MaxPermSize) accordingly. It does not make sense to switch to 64 bit if you dedicate less than double amount of memory to the application.
The recommended approach is to start with initial settings and monitor for the percentage of used memory (see also TW-13452) at the Administration | Diagnostics page. If the server uses more then 80% of memory consistently without drops for tens of minutes, that is probably a sign to increase the memory values by another 20%.
Configuring TeamCity Server
Configuring TeamCity Data Directory
The default placement of the TeamCity data directory can be changed. See corresponding section: TeamCity data directory for details.
Editing Server Configuration
After successful server start, any TeamCity page request will redirect to prompt for the server administrator username and password. Please make sure that no one can access the server pages until the administrator account is setup.
After administration account setup you may begin to create Project and Build Configurations in the TeamCity server. You may also want to configure the following settings in the Server Administration section:
- Server URL
- Email server address and settings
- Jabber server address and settings