Installing and Configuring the TeamCity Server

Installing the TeamCity Server

After you obtained the TeamCity installation package, proceed with corresponding installation intructions:

installingViaExecutable
installingWithTomcat
installingJ2eeContainer

After installation, TeamCity web UI can be accessed via web browser. Default addresses are http://localhost/ for Windows distribution and http://localhost:8111/ for tar.gz distribution.

If you cannot access TeamCity web UI after successful installation, please refer to 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.

When prompted, specify the server configuration directory (aka TeamCity Data Directory). Make sure the path to this directory contains latin charachters only, if you're planning to use default HSQLDB database.

If you opted to install the services, use standard Windows Services applet to manage the service. Otherwise, use standard runStopServer.

If you did not change the default port (80) during installation, the TeamCity web UI can be accessed via "http://localhost/" address in a web browser. Please note that 80 port 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)

Please review Supported Platforms and Environments before the installation.

Unpack TeamCity<version number>.tar.gz archive (for example, using tar xfz TeamCity<version number>.tar.gz command under Linux, or WinZip, WinRar or alike utility under Windows). Please use GNU tar to unpack. (for exapmple, Solaris 10 tar is reported to truncate too long file names and may cause a ClassNotFoundException. Consider getting GNU tar at Solaris packages or using gtar xfz command)

Ensure you have JRE or JDK installed and JAVA_HOME environment variable is pointing to Java installation directory. Latest Sun Java 1.6 update is recommended.

Starting TeamCity server

If TeamCity server is installed as Windows server, follow the usual procedure of starting and stopping services.

No matter how TeamCity is installed, TeamCity server can be started and stopped by the scripts provided in the <TeamCity home>/bin directory.

To start/stop TeamCity server and one default agent at the same time, use the runAll script. To start/stop only the TeamCity server, use teamcity-server script.

For example:

Use runAll.bat start to start the server and the default agent
Use runAll.bat stop to 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 changingServerPort for changing the server port.

If you need to pass special properties to the server, please refer to TeamCity Startup Properties.

Installing TeamCity into Existing J2EE Container

Copy the downloaded TeamCity<version number>.war file into the web applications directory of your J2EE container under teamCity.war name.
To configure TeamCity logging system, modify J2EE container settings to pass the following JVM options to the TeamCity web application: -Dlog4j.configuration=file:../conf/teamcity-server-log4j.xml -Dteamcity_logs=../logs/

Up to date values and conf/teamcity-server-log4j.xml file can be looked up in the bin/teamcity-server script available in .exe and tar.gz distributions. Sample file.

Ensure TeamCity web application is devoted sufficien amount of memory. Please increase the sizes accordingly if you have other web applications running in the same JVM.
If you are deploying TeamCity to Tomcat container, please add useBodyEncodingForURI="true" attribute to the Connector tag for the server in Tomcat/conf/server.xml file.
Restart the server or deploy the application via servlet container administration interface and access http://server/TeamCity-NNN/, where "TeamCity-NNN" is the name of the war file.

TeamCity J2EE container distribution is tested to work with Tomcat 6.x servlet container. (Tomcat version 5.5.20 is not compatible with TeamCity because this version of Tomcat contains a number of errors)

Installation Configuration

Troubleshooting TeamCity Installation

Upon successful installation, 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 TeamCity web UI cannot be accessed, please check:

the "TeamCity Server" service is running (if you installed TeamCity as a Windows service);
TeamCity server process (Tomcat) is running (it is java process run in <TeamCity home>/bin directory);
if you run the server from a console, check console output;
check teamcity-server.log and other files in the <TeamCity home>\logs directory 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 changingServerPort on changing the default port.

Changing Server Port

If you use TeamCity server Windows installer you can set the port to use during installation. If you use .war distribution please refer to the manual of the application server used.

Use the following instructions to change the port if you use .tar.gz distribution If another application uses the same port that TeamCity server, 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's port, in the < TeamCity Home >/conf/server.xml file, change the port number in the HTTP/1.1 connector (here the port number is 8111):

<Connector port="8111" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" enableLookup="false" useBodyEncodingForURI="true" />

To apply changes, you should 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).

Java Installation

TeamCity server is a web application that runs in an J2EE application server (a JVM application). A JVM application requires a JRE installation to run.

TeamCity (both server and agent) requires JRE 1.5 (or later) to operate. Using Sun JSDK 1.6 is recommended (download page). Please also note that TeamCity agent needs JDK (not JRE) to operate properly.

The necessary steps to prepare Java installation depends on the distribution used.

Windows Installer (.exe) has JRE bundled (in jre directory). If you need to update the JRE used by the installation:
- if you run the server from console refer to instructions for .tar.gz distribution below.
- if you run as Windows service and want to upgrade JRE to newer 32 bit version, you can replace <TeamCity home>\jre with JRE from the newer installation.
- if you run as Windows service and want to upgrade JRE to 64 bit version, you will need to replace <TeamCity home>\jre with appropriate JRE and also replace/update bundled Tomcat distribution to x64 version (use x64 versions of tomcat6.exe and tomcat6w.exe from matching x64 Tomcat installation).
.war distribution depends on the application server used. Please refer to the manual of the server.
To use .tar.gz distribution and teamcity-server or runAll scripts you need to have JRE installed either in <TeamCity home>\jre or into another location. If another location is used, ensure there is no <TeamCity home>\jre directory present and one of the environment variables is defined: JRE_HOME (pointing to home directory of installed JRE), or JAVA_HOME (pointing to home directory of installed JSDK).

Setting Up Memory settings for TeamCity Server

As a JVM application, TeamCity utilizes only the memory devoted to the JVM. The setting for the memory should be TeamCity Startup Properties as -Xmx (heap space) -XX:MaxPermSize (PermGen space) options for the JVM running the TeamCity server.

If you run TeamCity via runAll or teamcity-server scripts or via Windows service installed during TeamCity installation, the default setting of 512 Mb for the heap and (since TeamCity 5.1) 150 Mb for the PermGen are used. If you need to change the settings, please refer to TeamCity Startup Properties. If you run TeamCity using .war distribution please refer to the manual of the application server to change the memory settings. The actual memory consumption will be (e.g. 100Mb) higher since JVM itself uses memory too.

32 bit JVM can use up to 1.3Gb memory. If more memory is necessary, 64 bit JVM should be used assigning not less then 2.5Gb. It's highly unlikely that you will need to dedicate more then 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 -Xmx and -XX:MaxPermSize) accordingly.

Using 64 bit Java to Run TeamCity Server

TeamCity can run under both 32 and 64 bit JVM. It is recommended to java 32 bit JVM unless you need to dedicate more then 1.3Gb of memory to the TeamCity process.

If you choose to use x64 JVM please note that the memory usage is almost doubled when switching from 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.

Configuring the 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

Last modified: 20 April 2023