In this post, I will show you how to install the TeamCity Continuous Integration tool, and have it monitor a project.
Here’s a video you can watch, if you prefer learning with a video. However, the video does not show anything that is not in this lesson (in case you prefer a text lesson).
What is Continuous Integration, and why do I need it?
If you aren’t familiar with Continuous Integration (often abbreviated to CI), it’s a technique to help improve the quality of your projects. Every time you save changes to your source control repository, your CI tool will get the latest version of the source code and rebuild the solution. Then, you will receive a notification of whether or not the build was successful.
Also, if you created unit tests for your source code, the CI tool will run them and let you know if the tests succeeded or failed.
This way, if there are any problems, you will know about them a few minutes after you check in your changes – when you still remember everything you did. This is much better than finding out about a problem a week after you checked in your changes.
By the way, if you aren’t familiar with source control, or making unit tests for your projects, you can watch these two videos:
You can download TeamCity, from JetBrains, here: https://www.jetbrains.com/teamcity/. It’s free for anyone who only needs to use it for 20 projects or less.
The download was 628 megabytes, when I downloaded it. It will use around 837 megabytes of disk space, plus some working space for your projects and test results, when you install it.
NOTE: For this installation, we will install TeamCity to run on our computer. If you are working with other developers, and have a separate “build server” (a computer that only does continuous integration), you will want to install TeamCity on that computer.
Step 1: Download the installer from the link above and run it.
You can accept the starting defaults for most of the settings, unless you want to install it in a different location.
Step 2: When you get to the “Choose Components”, ensure these options are all checked:
- Build Agent
- Windows Service
- Windows Service
Step 3: During the installation, you will see a screen that asks for the “TeamCity server port:”. The default value is “80”.
If you aren’t familiar with “ports”, think of them as being a phone number for a program. If one program wants to communicate with another program, one way to do that is over its port.
TeamCity wants to know which port (phone number) it should “listen” on.
Port 80 is normally used to communicate with web browsers (Chrome, Firefox, etc.). But, if we use port 80, we might have a problem if we run IIS or Apache, two popular web servers you might install, if you plan to develop any website projects. So, we will use a different port.
I use port 9191. The ports in the 9000s are usually available for your programs.
Step 4: Next, TeamCity will show you the configuration properties screen. Check the “serverUrl” value. This is the URL you will put in your browser when you want to go to status page for your TeamCity installation.
Step 5: TeamCity will ask which Windows accounts to use to run the services. I choose the SYSTEM accounts.
If you want to be extra safe, you could create a new Windows account, specifically for TeamCity, and use that to run the services. However, if you are not on a network, you probably don’t need to add this extra layer of security.
Step 6: Set the TeamCity build notification so it automatically runs every time you start your computer.
In the System Tray, right-click on the TeamCity icon (the grey circle, with the question mark) and slick on “Run on Startup”
Step 7: Open your browser and go to the URL listed from the config file screen. This will include the port number you chose.
For me, the URL is “localhost:9191”.
Step 8: Select the data directory for TeamCity to use for its builds. If you don’t have much free disk space on one drive, you can create a new folder for TeamCity to use, and fill it in here.
Step 9: The Database Connection Setup screen.
You can configure TeamCity to use several different databases. I’ve always let it use its own internal database. This way, you don’t need to worry if you need to uninstall, or upgrade, the other database server that you choose here.
Step 10: The first time you start TeamCity, you’ll need to create an administrator account. You will use this account to manage the TeamCity builds (the projects you are watching in your source control, and what you want TeamCity to do when it notices a check-in).
Step 11: Install the Windows Tray Notifier.
After you log in the first time, you’ll be shown the “My Settings & Tools” page. From here, you can change your account information and download some more tools.
I always install the Windows Tray Notifier. This is a program that sits in your system tray and lets you know when TeamCity is building a project you want to monitor. This is the most important tool to me. If I check in a change, and it breaks the build, this is what will pop up a little message, letting me know about the problem.
Download the installer and run it.
Step 12: Click on the Windows Tray Notifier, in the system tray (it’s icon is the grey circle, with a question mark in it).
Fill in your TeamCity URL (http://localhost:9191, for me). Then, enter your TeamCity user name and password.
If you want the tray notifier to run every time you start your computer, right click on the system tray TeamCity icon and select “Run on Startup”.
Adding a project to TeamCity continuous integration
Now, I’m going to configure TeamCity to watch a solution of mine, “UnitTestDemo”.
Step 1: Open your browser and go to the address “http://localhost:9191” (or, whatever port number you used, if you did not use 9191).
Click on the “Projects” link, in the upper-left corner of the web page.
Click on the button that says “+ Create Project”.
This project does not have a parent project, so I will leave the “Parent Project” dropdown set to “<Root project>”. If you ever build a group of programs, that share some common code, you might use this parent project.
For the “Name”, I’ll use “Unit Test Demo”.
Click on the “Create” button.
Step 2: Add your build configuration. This is the information TeamCity needs to know where your source code is, and when you want it to build your project.
Click on the “+ Create build configuration” button.
NOTE: This is where you are limited, when using the free version of TeamCity. You can only have 20 build configuration running. If you get to 20, you can delete a build configuration for your older projects, if you aren’t making any more changes to them.
For the “Name”, I’ll use “CodeCheckIn”, since I want this to run after every check-in to the source code repository.
Click the “Create” button.
Step 3: Add information about your source code repository.
For my project, I’m using Subversion. So, I’ll select “Subversion” for “Type of VCS”.
I’ll use “UnitTestDemo” for the “VCS root name”.
The “URL” is the location of your source code repository. If you are using TortoiseSVN, you can right-click on the solution’s folder, select TortoiseSVN -> Repo Browser, and get the URL from here. My repository is located at: “file:///C:/Repositories/CSharp/Training/UnitTestDemo/trunk”.
If you have a username and password, for connecting to your repository, you would enter them here.
Because this is my personal development computer, at home, I’m not using usernames. However, if you are working with a shared project, you might want to create an account that only has “read” permissions to your source code repository, and use that account for your continuous integration tool.
Click on the “Test connection” button, to test that you entered the information correctly. You should see a popup that says “Connection Successful!”. If you do, click on the “Create” button.
Step 4: Add the build steps. These are the instructions TeamCity will use to build your project.
On the left side of the screen, click on the “Build Steps” link.
Click on the “+ Add build step” button.
The “Runner type” dropdown has several options. If you are using a special tool to build your project, you would select it here. I’m going to do the simplest version here, and tell TeamCity to build this solution, using the solution file and Visual Studio. So, I’ll select the option “Visual Studio (sln)”. If you normally use the “Build” button, inside Visual Studio, to compile and run your project, you should be safe selecting this option.
For “Solution file path”, click on the tree-view picture to the right of the textbox. This will display the files in your repository. Click on the solution file name to fill the textbox.
Choose your version of Visual Studio, for the “Visual Studio” dropdown.
For “Targets”, I choose “Clean”. That will remove the old version from TeamCity’s work area, and completely rebuild all the projects in the solution. That’s the safest way.
For “Configuration”, I always choose “Release”. That way, I can be sure the build will be the same one I would use to release the program to users.
Finally, click on the “Save” button.
If you have unit tests in your project, and you want them run, you would add another build step here. But, you need to have a few other things prepared to add that in, and I’m currently switching over to use xUnit for my unit testing. So, I’ll show how to connect xUnit tests in another video.
Step 5: Let TeamCity know when to run its build and test.
Click on “Triggers”, on the left side menu, and click on the “+ Add new trigger” button.
Choose “VCS Trigger” from the dropdown.
You might want to create a “Schedule Trigger” if you want TeamCity to run its build configuration at a specific time. This is useful if you ever add integration tests (which might take a long time to run). Then, you can create a build that runs those tests, in the middle of the night, when nothing else is happening.
Step 6: For this guide, I’m showing the basics you need, to get started with TeamCity. So, we won’t go over the other special configuration settings.
Right now, you are ready to run your build.
Click on the “Projects” in the top-left of the web page. Now you should see the build configuration for your solution.
Click on the “Run” button, on the right side of the page, and you should see TeamCity get the latest copy of your source code, build the solution, and (hopefully) display a green “Success” status.
Now, TeamCity is watching the source code repository for this project. Open your solution in Visual Studio, make a small change (maybe, add a comment), and check in that change.
Within a minute, you should see TeamCity build your solution again.
To me, this is one of the first steps to ensure your code maintains a high level of quality. You need to be sure that you can always “get latest” from your source code repository, and correctly rebuild your solution.
Someone who can’t do that, will almost always have other problems in their solution.
Automated tools like TeamCity help us by ensuring we never forget this step. Programs are already complex enough. Any tool I can use to help me, is a welcome addition to my programming practice.