Installing and Configuring the TeamCity Server

Last modified: 20 April 2023

Installing the TeamCity Server



Having obtained the TeamCity installation package, proceed with installing the build server for:

tip

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 setting up and running additional build agents.

note

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.

Installing TeamCity via executable file (Windows only)



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. The server can also be started/stopped with the help of provided runStopServer.

tip

If you want to edit the TeamCity server's service parameters, memory settings or system properties after the installation, please refer to the TeamCity Startup Properties section.

warning

Please make sure the service account has:

  • write permissions for the TeamCity Data Directory,

  • all the necessary permissions to work with the source controls used. This includes:

    • access to Microsoft Visual SourceSafe database (if Visual Source Safe integration is used).

    • the user, under which TeamCity server service runs, and ClearCase view owner are the same (if 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)

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. Sun Java is recommended.

TeamCity server can be started and stopped by the scripts provided in the <TeamCity home>/bin directory

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

To start/stop only the TeamCity server, use teamcity-server script (available since TeamCity 3.1).

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.

The port number can be edited in the <TeamCity home>/conf/server.xml file, line <Connector port="8111" protocol="HTTP/1.1". If you need to pass special properties to the server, please refer to TeamCity Startup Properties.

note

If you are running TeamCity on a server that is not running a windowing system, for example, Linux, then you may encounter this error when hitting the Statistics page:

javax.el.ELException: Error reading 'graphInfo' on type jetbrains.buildServer.serverSide.statistics.graph.BuildGraphBean

You can resolve this problem by adding this to your catalina.sh file:

JAVA_OPTS="-Djava.awt.headless=true"

Alternatively, you can add it to a new setenv.sh file that sits in your bin directory. The same can be applied to any start up script if you are using an third party container.

Installing TeamCity into Existing J2EE Container



  1. Copy the downloaded TeamCity<version number>.war file into the web applications directory of your J2EE container under teamCity.war name.

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

  1. Ensure TeamCity web application can use at least 512Mb heap size and 128Mb of PermGen size (usually, this is done by specifying JVM options -Xmx512m -XX:MaxPermSize=128m). Please increase the sizes if you have other web applications running in the same JVM.

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

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

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.

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