Enable Single Sign-On (SSO) in TeamCity

Enable Single Sign-On (SSO) in TeamCity

TeamCity can use the Windows Active Directory to authenticate users. To configure TeamCity to automatically log in users who are already logged into the Windows domain enable the Single Sign-On (SSO) functionality.

  1. In the upper right corner of the TeamCity web interface select Administration,
  2. On the left side in the Server Administration section select Authentication,
  3. Under HTTP authentication modules click the Load preset… button,
  4. In the drop-down list select Microsoft Windows Domain,
  5. Click the Edit link of the Microsoft Windows domain,
  6. Enter the name of the domain in your organization. If you leave the Allow creating new users… checkbox enabled, when new users log into TeamCity they are placed into a default user role. Make sure that role does not give them any authority.

Accessing TeamCity using Single Sign-On (SSO)

  1. With your web browser navigate to MY_TEAMCITY_SERVER/ntlmLogin.html,
  2. If asked, enter your domain username and password once,
  3. Subsequent logins in the same browser will not require authentication while the browser stays open.

Upgrade TeamCity to version 2017

Upgrade TeamCity to version 2017

Create a backup of the database and the server before the upgrade

  1. Disable the Chef-Client scheduled task and Chef-Client service to make sure Chef does not alter the server during the upgrade.
  2. Disable the authorized agents to stop them picking new jobs.
  3. Stop the TeamCity process on the server,
    1. If TeamCity is started by a scheduled task at startup
      1. Disable the “teamcityserver” scheduled task in the Task Scheduler,
      2. Stop the “Java(TM) Platform SE binary” process in Task Manager.
    2. If TeamCity is running as a Windows Service
      1. Stop and disable the “TeamCity” service.
  4. Save a copy of the TeamCity configuration directories to the data drive and an outside location
    1. D:\TeamCity\conf to D:\backup\conf – TODAY’S_DATE
    2. D:\ProgramData\JetBrains\TeamCity\config to D:\backup\config – TODAY’S_DATE
      Some file names in the D:\ProgramData\JetBrains\TeamCity\config\projects directory can be very long, so save the backup close to the root of the drive.
  5. Create a backup image of your server,
  6. Create a backup snapshot of your database,
  7. If the image creation did not restart the server, restart the box to make sure no processes hold files in the TeamCity install folder.

Download the TeamCity installer

  1. Turn off the Internet Explorer Enhanced Security Configuration,
  2. Enable file download on your server. Set the Internet Explorer security level to Medium-high
  3. Download the TeamCity server installer
    1. To download the latest TeamCity version navigate to
      http://www.jetbrains.com/teamcity/download/
    2. For earlier versions go to https://confluence.jetbrains.com/display/TW/Previous+Releases+Downloads

Install the new version of TeamCity server

  1. Execute the downloaded installer from the Downloads folder,
  2. If the current version of TeamCity is not on the C drive, make sure you select the correct drive,
  3. JetBrains recommends the uninstallation of the previous version of TeamCity,
  4. JetBrains does not recommend the agent instalation on the server, disable it,
  5. Run TeamCity under the SYSTEM account,
  6. To start TeamCity, leave the checkbox selected,
  7. TeamCity can automatically open the web user interface in your default browser,

TeamCity configuration

When you first try to launch the TeamCity server on a 64 bit Windows, you may get the message:

This page can’t be displayed

•Make sure the web address http://localhost:8111 is correct.
•Look for the page with your search engine.
•Refresh the page in a few minutes.

 

The D:\TeamCity\logs\teamcity-winservice.log file also contains the error message:

ProcessCommand [Info] Process exited with code: 1
console [Info] Error: Could not create the Java Virtual Machine.
console [Info] Error: A fatal exception has occurred. Program will exit.
console [Info] Invalid maximum heap size: -Xmx10g
console [Info] The specified size exceeds the maximum representable size.
ServiceExecuteProcessTask [Error] Service process exited without service stop request

Follow the instructions below to switch to 64 Java.

 

TeamCity on 64-bit Java

The TeamCity installer also installs the 32-bit version of the Java Runtime Environment (JRE) in the “D:\TeamCity\jre” folder. To use the 64 bit Java, test if your server has  64-bit Java installed:

  1. Open a command window and execute,
    java.exe -d64 -version
  2. The installed Java is 32 bit if you get the error message:
    Error: This Java instance does not support a 64-bit JVM.
    Please install the desired version.

Switch to 64-bit Java

  1. Stop the TeamCity Windows Service,
  2. Rename the D:\TeamCity\jre to jre_32bit, so TeamCity will not find it anymore,
  3. If you have not specified the memory settings in the Set the TEAMCITY_SERVER_MEM_OPTS environment variable based on the physical memory size of your server and the estimated usage
    1. Start Windows Explorer
    2. Right-click This PC and select Properties
    3. Select Advanced system settings
    4. Click the Environment Variables… button
    5. In the System Variables section select TEAMCITY_SERVER_MEM_OPTS
    6. Set the value based on the expected server load:
      1. minimum setting for 32-bit and 64-bit java:
        -Xmx750m
      2. recommended setting for medium 64-bit server and maximum for 32-bit server:
        -Xmx1024m
      3. recommended setting for large server (64-bit java only):
        -Xmx4g -XX:ReservedCodeCacheSize=350m
      4. maximum settings for large-scale server use (64-bit java only):
        -Xmx10g -XX:ReservedCodeCacheSize=512m

Source: https://confluence.jetbrains.com/display/TCD10/Installing+and+Configuring+the+TeamCity+Server#InstallingandConfiguringtheTeamCityServer-SettingUpMemorysettingsforTeamCityServer

Finish the TeamCity upgrade

  1. Start the TeamCity Server Windows service,
  2. Open a web browser and navigate to http://localhost:8111/
  3. Click the I’m a server administrator… link,
  4. Find the authentication token at the end of the D:\TeamCity\logs\teamcity-server.log file
  5. Enter it into the textbox
  6. Allow TeamCity to make a backup of your current data,
  7. TeamCity will display the progress of the backup process.
  8. TeamCity will automatically start the server initialization.
  9. And finally, will display the login page.

 

Disaster recovery

If for some reason the server does not work after the upgrade, you can restore the database and the server from the backups you made before the upgrade.

Rebuild the environment

  1. Terminate the failed TeamCity server
  2. Restore the database from the backup snapshot
  3. Launch a new server instance from the backup server image

Make sure that the TeamCity process is not running on the restored server

When the server has started, remote into it.

  1. Check if the TeamCity process has ben stopped:
    1. If TeamCity is started by a scheduled task at startup
      1. Disable the “teamcityserver” scheduled task in the Task Scheduler,
      2. Stop the “Java(TM) Platform SE binary” process in Task Manager.
    2. If TeamCity is running as a Windows Service
      1. Stop and disable the “TeamCity” service.

Update the server configuration

TeamCity stores the address of the database and the IP address of the server in config files. To be able to use the restored server, make the following changes:

Update the database address

  1. Update the database address in the connectionUrl line of D:\ProgramData\JetBrains\TeamCity\config\database.properties

Update the IP address of the server

  1. Update the server IP address in the server rootURL element of D:\ProgramData\JetBrains\TeamCity\config\main-config.xml

Start TeamCity

  1. Start the TeamCity service or scheduled task

Test the TeamCity server

  1. Open a web browser on the server and navigate to http://localhost:8111/

Load Balancer

  1. Attach the server to the load balancer

Monitor timeouts in TeamCity

TeamCity is a Continuous Integration (CI) tool that enables software development teams to build and test their software. Sometimes the server is too busy to serve the users and the web user interface does not respond in time. TeamCity logs all actions in a log file so we can find the date and time of these timeouts:

On Windows

  1. Remote into the TeamCity server,
  2. Open the server log file at D:\TeamCity\logs\teamcity-server.log

Scroll to the bottom of the file and search for “Request processing took too long” going up to find the last timeout event.

Upgrade TeamCity to version 10

Upgrade TeamCity to version 10

Create a backup of the database and the server before the upgrade

  1. Disable the Chef-Client scheduled task and Chef-Client service to make sure Chef does not alter the server during the upgrade.
  2. Disable the authorized agents to stop them picking new jobs.
  3. Stop the TeamCity process on the server,
    1. If TeamCity is started by a scheduled task at startup
      1. Disable the “teamcityserver” scheduled task in the Task Scheduler,
      2. Stop the “Java(TM) Platform SE binary” process in Task Manager.
    2. If TeamCity is running as a Windows Service
      1. Stop and disable the “TeamCity” service.
  4. Save a copy of the TeamCity configuration directories to the data drive and an outside location
    1. D:\TeamCity\conf
    2. D:\ProgramData\JetBrains\TeamCity\config
      Some file names in the D:\ProgramData\JetBrains\TeamCity\config\projects directory can be very long, so save the backup first in the root of the data drive
  5. Create a backup image of your server,
  6. Create a backup snapshot of your database,
  7. If the image creation did not restart the server, restart the box to make sure no processes hold files in the TeamCity install folder.

Download the TeamCity installer

  1. Enable file download on your server. Set the Internet Explorer security level to Medium-high
  2. Download the TeamCity server installer
    1. To download the latest TeamCity version navigate to
      http://www.jetbrains.com/teamcity/download/
    2. For earlier versions go to https://confluence.jetbrains.com/display/TW/Previous+Releases+Downloads

Install the new version of TeamCity server

  1. Execute the downloaded installer from the Downloads folder,
  2. If the current version of TeamCity is not on the C drive, make sure you select the correct drive,
  3. It is not recommended to run agents on the server box. Uncheck the Windows Services and Core for the Build Agent,
  4. If you get Folder is not empty… messages, delete the files from the indicated locations and click the Retry button,
  5. Set the correct port TeamCity should to use 
  6. Even if you haven’t enabled the agent functionality on the TeamCity server, you will see the Configure Build Agent Properties page. Click the Save button to continue.
  7. Select the SYSTEM account to run the TeamCity service
  8. Click the Next button to start the TeamCity service

Warning:

If you have specified larger memory setting than 32 bit Java is capable of handling, the TeamCity service will not start. You will get the following error message in D:\TeamCity\logs\teamcity-winservice.log

ProcessCommand [Info] Process exited with code: 1
console [Info] Error occurred during initialization of VM
console [Info] Could not reserve enough space for 2097152KB object heap
ServiceExecuteProcessTask [Error] Service process exited without service stop request

To switch to 64 bit Java, follow the steps below.

TeamCity on 64-bit Java

The TeamCity installer also installs the 32-bit version of the Java Runtime Environment (JRE) in the “D:\TeamCity\jre” folder. To use the 64 bit Java, test if your server has  64-bit Java installed:

  1. Open a command window and execute,
    java.exe -d64 -version
  2. The installed Java is 32 bit if you get the error message:
    Error: This Java instance does not support a 64-bit JVM.
    Please install the desired version.

Switch to 64-bit Java

  1. Stop the TeamCity Windows Service,
  2. Rename the D:\TeamCity\jre to OLD_jre, so TeamCity will not find it anymore,
  3. If you have not specified the memory settings in the Set the TEAMCITY_SERVER_MEM_OPTS environment variable based on the physical memory size of your server and the estimated usage
    1. Start Windows Explorer
    2. Right-click This PC and select Properties
    3. Select Advanced system settings
    4. Click the Envirnment Variables… button
    5. In the System Variables section select TEAMCITY_SERVER_MEM_OPTS
    6. Set the value based on the expected server load:
      1. minimum setting for 32-bit and 64-bit java:
        -Xmx750m
      2. recommended setting for medium 64-bit server and maximum for 32-bit server:
        -Xmx1024m
      3. recommended setting for large server (64-bit java only):
        -Xmx4g -XX:ReservedCodeCacheSize=350m
      4. maximum settings for large-scale server use (64-bit java only):
        -Xmx10g -XX:ReservedCodeCacheSize=512m

Source: https://confluence.jetbrains.com/display/TCD10/Installing+and+Configuring+the+TeamCity+Server#InstallingandConfiguringtheTeamCityServer-SettingUpMemorysettingsforTeamCityServer

Remove unsupported memory settings

TeamCity version 10 does not use -XX:MaxPermSize anymore. If you get

[Info] Java HotSpot(TM) Server VM warning: ignoring option MaxPermSize=2048m; support was removed in 8.0

remove “MaxPermSize” from theTEAMCITY_SERVER_MEM_OPTS environment variable.

Start the server

  1. Open Services and start the TeamCity Server Windows service
  2. Open a web browser and navigate to http://localhost:8111
  3. On the TeamCity Maintenance page select the I’m a server administrator, show me the details link
  4. Open the D:\TeamCity\logs\teamcity-server.log file and find the Administrator can login from web UI using authentication token line and copy the token number to the clipboard
  5. Paste the token to the textbox and click the Confirm button
  6. On the TeamCity Upgrade page click the Upgrade button
  7. TeamCity will make a backup of the current projects to D:\ProgramData\JetBrains\TeamCity\backup

Disaster recovery

If for some reason the server does not work after the upgrade, you can restore the database and the server from the backups you made before the upgrade.

Rebuild the environment

  1. Terminate the failed TeamCity server
  2. Restore the database from the backup snapshot
  3. Launch a new server instance from the backup server image

Make sure that the TeamCity process is not running on the restored server

When the server has started, remote into it.

  1. Check if the TeamCity process has ben stopped:
    1. If TeamCity is started by a scheduled task at startup
      1. Disable the “teamcityserver” scheduled task in the Task Scheduler,
      2. Stop the “Java(TM) Platform SE binary” process in Task Manager.
    2. If TeamCity is running as a Windows Service
      1. Stop and disable the “TeamCity” service.

Update the server configuration

TeamCity stores the address of the database and the IP address of the server in config files. To be able to use the restored server, make the following changes:

Update the database address

  1. Update the database address in the connectionUrl line of D:\ProgramData\JetBrains\TeamCity\config\database.properties

Update the IP address of the server

  1. Update the server IP address in the server rootURL element of D:\ProgramData\JetBrains\TeamCity\config\main-config.xml

Restart

  1. Restart the box for the changes to take effect.

Secure passwords in TeamCity

When a TeamCity build step needs to use a password, there is a secure way to store it.

  1. In the TeamCity web interface navigate to the project,
  2. On the project page open the Parameters page,
  3. Click the Add new parameter button,
  4. Enter the name of the parameter, the password value, and click the Edit button to set the special settings,
  5. Set the Display to Hidden, and the Type to Password to hide the value from the user interface. Click the Save button on this window and the on the parent window to save the parameter.
  6. To use the parameter in a build step, surround it with % signs.

How to rename a TeamCity agent

It is important to keep the TeamCity agent names unique. If you launch a TeamCity agent with a name that is already used by another agent that is connected to the TeamCity server, the new agent will not show up in the Unauthorized agent list.

To change the name of an agent, change the “name” value in the conf/buildAgent.properties file.

To access the file you need to log into the box.

On a Linux agent

  • SSH into the agent,
  • Change the “name” value in the /opt/teamcity/conf/buildAgent.properties file.

On a Windows agent

  • Remote into the agent,
  • Change the “name” value in the C:\TeamCity\conf\buildAgent.properties file.

The location of TeamCity can be different depending on the configuration of the box.

Enable user to import projects in TeamCity

It is not enough to belong to the “System Administrator” group to be able to import projects from backup  in TeamCity. The user has to be in the “System administrator” role for the “Root project”.

To enable the user to import projects into TeamCity

  • Click the Administration link in the upper right corner
  • In the User Management section click Users
  • Click the user name in the list
  • On the Roles tab click the + Assign role button
  • Set the Role to System administrator
  • Set the Scope to Root project
  • Select the Replace existing roles with newly selected check box and click the Assign button