Installing and Configuring the TeamCity Server

- [Download|http://www.jetbrains.com/teamcity/download/] the distribution
- Review [software requirements|Supported Platforms and Environments] and [hardware requirements notes|How To...#Estimate hardware requirements for TeamCity]
- Review [Licensing Policy] and [TeamCity Editions]
- Install and configure the TeamCity server per instructions below

*This page covers:*
{toc}

h2. Installing the TeamCity Server

After you obtained the TeamCity installation package, proceed with corresponding installation instructions:
* [Windows .exe distribution|#installingViaExecutable] \- executable which provides installation wizard for Windows platforms and allows to install server as a Windows service;
* [.tar.gz distribution|#installingWithTomcat] \- archive with "portable" version suitable for all platforms;
* [.war distribution|#installingJ2eeContainer] \- for experienced users that want to run TeamCity in separately installed Web application server.

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.

{panel} (i) The build server and one build agent will be installed by default for Windows, Linux or MacOS X. If you need more build agents, refer to the section [Installing Additional Build Agents|setting up and running additional build agents]. {panel}

{panel} (!) By default, TeamCity uses an HSQLDB database that does not require special configuring. This database works fine for testing and evaluating the system.
\\
For production purposes using a standalone external database is recommended.
* [Setting up an External Database]
* [Migrating to an External Database]
{panel}

{anchor:installingViaExecutable}

h3. 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 standard Windows {{Services}} applet to manage the service.
Otherwise, use standard [scripts|#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.

{anchor:ConfiguringTomcatServiceSettings}
{panel} (i) If you want to edit the TeamCity server's service parameters, memory settings or system properties after the installation, please refer to the [Configuring TeamCity Server Startup Properties] section.{panel}

{warning:title=Service account}
Please make sure the service account has:
* write permissions for the [TeamCity Data Directory|TeamCity Data Directory],
* all the necessary permissions to work with the source controls used. This includes:
** access to Microsoft Visual SourceSafe database (if [Visual SourceSafe] integration is used).
** the user, under which TeamCity server service runs, and ClearCase view owner are the same (if [ClearCase|ClearCase] integration is used).

By default, Windows service in installed under SYSTEM ACCOUNT. To change it, use the Services applet (*Control Panel \| Administrative Tools \| Services*)
{warning}

{anchor:installingWithTomcat}

h3. Installing TeamCity bundled with Tomcat servlet container (Linux, Mac OS X, Windows)

Please review [software requirements|Supported Platforms and Environments#The TeamCity Server] 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|http://sunfreeware.com/] or using {{gtar xfz}} command)

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

{anchor:runStopServer}

h3. 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 [below|#changingServerPort] for changing the server port.

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

{note:title=Headless mode for TeamCity}If you are running TeamCity on a server that is not running a windowing system, for example, console mode under Linux, then you may encounter this error when hitting the Statistics page:
{panel}javax.el.ELException: Error reading 'graphInfo' on type jetbrains.buildServer.serverSide.statistics.graph.BuildGraphBean{panel}
You can resolve this problem by adding {{\-Djava.awt.headless=true}} [server JVM option|TeamCity Startup Properties#JVM Properties].
{note}

{anchor:installingJ2eeContainer}

h3. 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 or deploy the .war following documentation of the web server. Please make sure there is no other version of TeamCity deployed (e.g. do not preserve old TeamCity web application directory under web server applications directory).
# Configure TeamCity [logging properties|TeamCity Server Logs#log4jConfiguration] by specifying {{log4j.configuration}} and {{teamcity_logs}} properties. 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 {{[^teamcity-server-log4j.xml]}} file.
# Ensure TeamCity web application is devoted sufficient amount of [memory|#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.
# If you are deploying TeamCity to *Jetty* container version >7.5.5 (including 8.x.x) please make sure system property {{org.apache.jasper.compiler.disablejsr199}} is set to {{true}}
# Ensure servlet container is configured to unpack deployed war files. Though for most servlet containers it is the default behaviour, for some it is not (e.g. Jetty version >7.0.2) and must be explicitly configured. TeamCity can not start while packed and will prompt about this in logs and UI.
# Configure appropriate [TeamCity Data Directory|TeamCity Data Directory] to be used by TeamCity.
# 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. You might also need to rename the file to exclude build number from the name.

TeamCity J2EE container distribution is tested to work with Tomcat 7 servlet container. (See also [Supported Platforms and Environments#The TeamCity Server])

h3. Autostart TeamCity server on Mac OS X

Starting up TeamCity server on a Mac is quite similar to starting Tomcat on Mac.

* Install TeamCity and make sure it works if started from command line, with *bin/teamcity-server.sh start*. We'll assume that TeamCity is installed in /Library/TeamCity folder
* Create file /Library/LaunchDaemons/jetbrains.teamcity.server.plist with the following content:
{code}
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>WorkingDirectory</key>
<string>/Library/TeamCity</string>
<key>Debug</key>
<false/>
<key>Label</key>
<string>jetbrains.teamcity.server</string>
<key>OnDemand</key>
<false/>
<key>KeepAlive</key>
<true/>
<key>ProgramArguments</key>
<array>
<string>bin/teamcity-server.sh</string>
<string>run</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>StandardErrorPath</key>
<string>logs/launchd.err.log</string>
<key>StandardOutPath</key>
<string>logs/launchd.out.log</string>
</dict>
</plist>
{code}

* Test your file by running *launchctl load /Library/LaunchDaemons/jetbrains.teamcity.server.plist* . This command should start TeamCity server (you can see this from logs/teamcity-server.log and in browser)
* If you don't want TeamCity to start under root permissions, specify *UserName* key in the plist file, like this:
{code}
<key>UserName</key>
<string>teamcity_user</string>
{code}
* That's it. TeamCity now should autostart when machine starts.

h3. Using another Version of Tomcat

If you want to use another version of Tomcat web server instead of bundled one, you have the choices of whether to use [.war TeamCity distribution|#Installing TeamCity into Existing J2EE Container] or do Tomcat upgrade/patch for TeamCity installed from .exe or .tar.gz distributions.
For the latter, you might want to:
- backup current TeamCity home
- delete/move out the directories from TeamCity home which are also present in Tomcat distribution
- unpack Tomcat distribution into TeamCity home directory
- copy TeamCity-specific files from the previously backed-up/moved directories to the TeamCity home. Namely:
-- files under {{bin}} which are not present in the Tomcat distribution
-- delete default Tomcat {{conf}} directory and replace it with TeamCity-provided one
-- delete default Tomcat {{webapps/ROOT}} directory and replace it with TeamCity-provided one


h2. Installation Configuration

h3. 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
[more|#changingServerPort] on changing the default port.


{anchor:changingServerPort}

h3. 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|TeamCity Specific Directories#tcHomeDir]}}{{>/conf/server.xml}} file, change the port number in the HTTP/1.1 connector (here the port number is 8111):
{code}
<Connector port="8111" protocol="HTTP/1.1"
connectionTimeout="20000"
redirectPort="8443"
enableLookup="false"
useBodyEncodingForURI="true"
/>
{code}

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

If you want to use 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]


{anchor:java}

h3. 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.6 (or later) to operate. Using latest Oracle JSDK 1.6 is recommended ([download page|http://java.sun.com/javase/downloads]). 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 (just install JRE per installation instructions and copy the content of the resulting directory to replace the content of the existing "jre" directory).
-- {anchor:x64tomcat}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 Windows binaries: copy/overwrite content of {{bin\x64}} directory to {{bin}}.
- {{.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).

{anchor:memory}

h3. Setting Up Memory settings for TeamCity Server

As a JVM application, TeamCity only utilizes memory devoted to the JVM. Memory used by JVM usually constitutes of: heap (configured via {{\-Xmx}}), permgen (configured via {{\-XX:MaxPermSize}}), internal JVM (usually tens of Mb), OS-dependent memory features like memory-mapped files. TeamCity mostly depends on heap and permgen memory and these settings can be configured for the TeamCity application manually by [passing|Configuring TeamCity Server Startup Properties#JVMProperties] {{\-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) minimum recommended settings are: {{\-Xmx750m \-XX:MaxPermSize=270m}}. If slowness or OutOfMemory error occurs, please increase the settings to {{\-Xmx1300m \-XX:MaxPermSize=270m}}.
* Maximum settings that you will ever probably need are (x64 JVM should be used): {{\-Xmx4g \-XX:MaxPermSize=270m}}. These settings will suit for an installation with more than a hundred of agents and thousands of build configurations.
* If you run TeamCity via {{runAll}} or {{teamcity-server}} scripts or via Windows service installed, the default settings used are: 512 Mb for the heap and 150 Mb for the PermGen.

To change memory settings, refer to [Configuring TeamCity Server Startup Properties|Configuring TeamCity Server Startup Properties#JVMProperties], or to the documentation of your application server, if you run TeamCity using .war distribution.

*Tips*:
* 32 bit JVM can use up to 1.3Gb memory. If more memory is necessary, 64 bit JVM should be used assigning not less than 2.5Gb. 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 {{\-Xmx}} and {{\-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 increase them whenever OutOfMemory error occurs (see also [TW-13452|http://youtrack.jetbrains.net/issue/TW-13452]).
{show-if:action=edit}
Minimum recommended settings for initial use of TeamCity for production purposes are {{\-Xmx750m \-XX:MaxPermSize=270m}}.
Maximum settings that you will ever probably need are (x64 JVM should be used): {{\-Xmx4g \-XX:MaxPermSize=270m}}. These settings should suit for an installation with more than a hundred of agents and thousands of build configurations.
The recommended approach is to start with the recommended settings and increase them whenever OutOfMemory error occurs (see also [TW-13452|http://youtrack.jetbrains.net/issue/TW-13452]).

The setting for the memory should be [passed|Configuring TeamCity Server Startup Properties#JVMProperties] 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 150 Mb for the PermGen are used. If you need to change the settings, please refer to [Configuring TeamCity Server Startup Properties|Configuring TeamCity Server Startup Properties#JVMProperties]. 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 than 2.5Gb. 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 {{\-Xmx}} and {{\-XX:MaxPermSize}}) accordingly.
{show-if}
{anchor:x64jvm}

h3. Using 64 bit Java to Run TeamCity Server

TeamCity can run under both 32 and 64 bit JVM.
It is recommended to [use|#java] 32 bit JVM unless you need to dedicate more than 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].

If you run TeamCity as a service and switch to x64 bit, you will also need to use x64 Tomcat executables, see [more|#x64tomcat].

h2. Configuring the TeamCity Server

{tip}* If you have a lot of projects or build configurations, we recommend you avoid using the *Default agent* in order to free up the TeamCity server resources. The TeamCity Administrator can disable the default agent on the *Agents* page of the web UI.
* When changing the TeamCity data directory or database make sure they do not get out of sync.
{tip}

{anchor:configuringDataDirectory}

h3. Configuring TeamCity Data Directory

The default placement of the TeamCity data directory can be changed. See corresponding section: [TeamCity data directory] for details.

{anchor:serverconfig}

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


\\
\\
{color:#003366}{*}See also:*{color}
{panel:borderStyle=dashed|bgColor=#FFFFFF}
*Installation and Upgrade*: [Setting Up and Running Additional Build Agents]
{panel}