Installation on Mac OS X

The TeamCity installation package (Teamcity-<version number>.tar.gz) can be downloaded from the download page at http://www.jetbrains.com/teamcity/download/.

TeamCity needs JRE or JDK 1.6+ to be installed. The recommended version is Oracle Java 1.7. It is ideal to have the JDK in case of the agent.

Note

The installation package is bundled with the Tomcat 7 servlet container. This is the recommended way to install TeamCity on OS X, unless you want to absolutely use your own installation of Tomcat or a different J2EE servlet container.

Running the TeamCity server and the default agent

The steps involved in getting an instance of the TeamCity server and agent up and running on OS X are listed as follows:

1. The downloaded installation package can be unpacked using a utility like Archive Utility in OS X. It can also be unpacked from the command line using the tar command:

   tar xvfz TeamCity-8.0.4.tar.gz
   

2. The package can be extracted, or the extracted contents can be copied over to the location where TeamCity is to be installed. Let's call this <TeamCity Home Directory>.
3. The runAll.sh script provided under the <TeamCity Home Directory>/bin directory can be used to start and stop the server and the default agent:
   • To start both the server and the default agent, run the following command:

     <TeamCity Home Directory>/bin/runAll.sh start
     

   • To stop both the server and the default agent, run the following command:

     <TeamCity Home Directory>/bin/runAll.sh stop
     

     Tip

     The scripts in the bin directory may need to be marked as an executable using the chmod +x bin/*.sh command.

4. The teamcity-server.sh script can be used to start the server alone:
   • To start the server, run the following command:

     <TeamCity Home Directory>/bin/teamcity-server.sh start
     

   • To stop the server, run the following command:

     <TeamCity Home Directory>/bin/teamcity-server.sh stop
     

5. Once the server has been started, the web interface can be accessed at the default port, 8111. This port can be changed by editing the highlighted section in the following piece of code from the <TeamCity Base Directory>/conf/server.xml file:

   <Connector port="8111" protocol="org.apache.coyote.http11.Http11NioProtocol"
       connectionTimeout="60000"
       redirectPort="8543"
       useBodyEncodingForURI="true"
       socket.txBufSize="64000"
       socket.rxBufSize="64000"
       tcpNoDelay="1"
       />

   Tip

   Downloading the example code

   You can download the example code files for all Packt books you have purchased from your account at http://www.packtpub.com. If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.

6. The TeamCity web interface should present the Teamcity First Start page.
7. By default, <Teamcity data directory> is located at $HOME/.BuildServer. Setting the TEAMCITY_DATA_PATH environment variable can change it from its default value. The data directory location has to be chosen carefully as it stores all of the data, including the build history and the artifacts. More information on the data directory can be found at http://confluence.jetbrains.com/display/TCD8/TeamCity+Data+Directory.
8. The first time installation asks you to agree to the license from the web interface, and you can also opt to send usage statistics to the developers. The initial administrator account also needs to be set up at this point.

Setting up the TeamCity server as a daemon

The previous installation steps are helpful when you want to run TeamCity manually, using the scripts provided. If you want TeamCity to be set up as a daemon so that it can autostart once the system is restarted, you'll need to follow some additional steps.

Tip

The setting up of a server as a daemon is an advanced concept. The steps given here are representative, and they only highlight what can be achieved. The actual steps and scripts involved will be different for different use cases.

This section is optional and can be skipped.

The steps to configure the TeamCity server as a daemon are as follows:

1. Create a file named jetbrains.teamcity.server.plist at /Library/LaunchDaemons with the following content:

   <?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>TeamCity Home Directory</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>
       <key>UserName</key>
       <string>Admin</string>
   </dict>
   </plist>

   The XML content provides the configuration for the daemon. As it can be seen, the ProgramArguments key holds the script to be run and the parameters to be passed to it. We are using run instead of start, as run starts the server in the process, whereas start creates a background process. WorkingDirectory is set to <TeamCity Home Directory>. The logfile paths are also configured relative to WorkingDirectory using the StandardErrorPath and StandardOutPath keys.

   The UserName key specifies the user the daemon should run under. Without this setting, it will run as the root (not recommended).

   You can learn more about the plist file and the property keys at https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man5/launchd.plist.5.html.

2. Once the plist file has been created, we can test that it all works by running the following command:

   sudo launchctl load /Library/LaunchDaemons/jetbrains.teamcity.server.plist
   

   The preceding command starts the TeamCity server. We can look at the launchd.err.log, launchd.out.log and teamcity-server.log files under <TeamCity Home Directory>/logs to confirm that the server is running without any issues.

   The following command can be run to stop the TeamCity server if needed:

   sudo launchctl unload /Library/LaunchDaemons/jetbrains.teamcity.server.plist
   

3. That's all there is to configure the TeamCity server as a daemon. The server should automatically start up the next time the system is restarted.

Installing additional agents

Note

The JRE or JDK 1.6+ is a prerequisite. (JDK is preferred for the agent since the agent may have to perform some build tasks that need the JDK.)

The steps involved in running additional agents on the same machine or on additional machines are as follows:

1. Additional agents can be easily installed from the Agents page (http://<serverUrl>:<serverPort>/agents.html).
2. The Install Build Agents link at the top-right corner of this page can be used to download the agent installer (Zip file distribution) directly from the server. The following screenshot shows the pop up that is presented when this link is clicked:
   
3. Unpack the downloaded archive and add it to the desired directory using the unzip command or the Archive Utility app. Let's call this directory <TeamCity Agent Home directory>.
4. Before starting the agents, the agent configuration properties have to be edited. The sample properties file, <TeamCity Agent Home directory>/conf/buildAgent.dist.properties, needs to be renamed to buildAgent.properties. In the file, the serverUrl property needs to be changed appropriately.
5. The default port for the agent is 9090. The agent must be able to communicate with the server on the server's port, and the server must be able to communicate with the agent on this default port.
6. Similar to the server and the default agent package, the startup scripts are located in the bin directory in <TeamCity Agent Home directory>. The agent can be started by running <TeamCity Agent Home directory>/bin/agent.sh start or <TeamCity Agent Home directory>/bin/agent.sh run. The former starts the agent in the background, whereas the latter will start it in the current console.
7. The agent can also be run as a daemon using launchd. The installation package comes with the necessary plist file, located at <TeamCity Agent Home directory>/bin/jetbrains.teamcity.BuildAgent.plist.
8. The WorkingDirectory property has to be changed to <TeamCity Agent Home directory>. The UserName property must be added and set with the user that the agent must run as, unless the agent needs to run as the root (not recommended).
9. The steps to install and test the plist file are similar to the server daemon's setup. Once the plist file is copied to /Library/LaunchDaemons/, the agent should start up automatically once the system is restarted.
10. Agents need to be authorized from the Agents page. Agents on the same machine as the server are approved automatically, whereas any other agent must be manually approved for it to be added to the list of available agents.