Move or clone from one hardware to another for Azure DevOps on-premises

Azure DevOps Server 2022 | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018

You can move or clone your deployment of Azure DevOps Server software. You move Azure DevOps Server from one machine to another by restoring it to new hardware (called a restoration-based move). For example, you might want to move Azure DevOps Server to a server with greater capacity or improved processing speed. When you move to a new server you do not lose any of your project history.

To clone your Azure DevOps Server deployment, you perform the same steps as a move plus a few additional ones.

You perform a move when you plan to discontinue use of the original hardware and Azure DevOps Server deployment. You perform a clone when you intend to continue using the original Azure DevOps Server instance.

Check your permissions

In order to successfully move Azure DevOps Server, you'll need to be an administrator on both sets of hardware (the old and the new). In addition, you'll need to be an administrator (or have the equivalent permissions) for Azure DevOps Server and all of the software on which your deployment depends: SQL Server, reporting, and any other software with which your deployment interoperates, such as Project Server.

Make sure you are a member of the following groups:

• Servers: Administrators (local Administrators group or equivalent)
• Azure DevOps Server: Team Foundation Administrators and Admin Console Users
• SQL Server: sysadmin

If you aren't a member of one or more of these groups, get permissions now.

Back up databases and encryption key

1. Open the administration console for Azure DevOps Server and on the Scheduled Backups page, take a full backup. The backup will back up everything you configured for backup in your backup plan, but it will do so immediately, not according to the time scheduled in the plan. If your deployment uses reporting, you can back up the encryption key as part of this backup set.

   

   (If you don't have backups configured, you'll have to create a plan before you can take a full backup.)

2. Once the backup completes, verify that the backup is available on the storage device or network share, and that you can access this backup from the new hardware.

Install and configure SQL Server on the new data-tier server

• Install SQL Server on the new server and make sure that it is operational. If your previous deployment used reporting, make sure that you include the reporting and analysis services components. You must install the same version and edition that you used previously, including service pack and cumulative update levels.

  

  As an alternative, you can create an instance of SQL Server on a server that already has a matching version installed and restore the Azure DevOps Server databases to that instance, but that will require more post-restoration configuration.

  For more information about options for installing and configuring SQL Server, go here.

  After installing SQL Server, if your deployment includes reporting, open SQL Server Management Studio and detach the ReportServer and ReportServerTempDB databases. Otherwise you might not be able to restore these databases with the backup you created for the Azure DevOps Server databases.

  

Install and configure software on the new application-tier server

To configure a new server or servers for Azure DevOps Server, you must first install and configure the software that is required to support it. This software includes the following components:

• a supported operating system for your deployment configuration

• Install and configure Windows, IIS (if not configured by default), and make sure that the server and its software are operational. 

  For more information, see the system requirements for Azure DevOps Server.

Restore the Azure DevOps Server databases

In order to restore the Azure DevOps Server databases using the restore tool, you must install but not configure Azure DevOps Server on the new data-tier server, and then use the restore function in the Scheduled Backups node.

If you want to restore Azure DevOps Server databases manually using SQL Server restoration tools, you can, but that is a more difficult procedure. In addition, you will have to manually unquiesce the databases in the new deployment. The restore wizard in Azure DevOps Server automatically does this for you as part of its restoration process, but that functionality is not part of SQL Server's restoration tools.

1. Launch the Azure DevOps Server installation media. On the Team Foundation Server Setup page, choose Install.

2. When the installation completes, the Team Foundation Server Configuration Center opens. Close it.

   The administration console opens automatically in an unconfigured state. This is expected.

3. To start the Restore wizard, open the administration console for Azure DevOps Server and open Scheduled Backups.

   

4. Specify the path to the backup set and choose the set you created after quiescing the old deployment.

   

5. Complete the wizard and restore the databases to the new instance of SQL Server.

   

(Clone option) Reconfigure server IDs and remap databases

Perform the next set of steps on the new application-tier server if you intend to continue using the original Azure DevOps Server instance. These steps are necessary to avoid the risk of corruption of one or both deployments. If both servers are live, you could end up with corruption, particularly if they are pointing to the same reporting resources.

1. Open a Command Prompt window as an administrator and change directories to Drive:%programfiles%\TFS 12.0\Tools. Open a Command Prompt window and enter:

2. Run the TFSConfig PrepareClone command to remove information about scheduled backups, and reporting resources.

   TFSConfig PrepareClone /SQLInstance:ServerName /DatabaseName:DatabaseName /notificationURL: ApplicationTierURL
   

3. Run the TFSConfig ChangeServerID command to change the server GUIDs that are associated with the databases. GUIDs must be unique within Azure DevOps Server deployment.

   TFSConfig ChangeServerID /SQLInstance:ServerName] /DatabaseName:ConfigurationDatabaseName [/ProjectCollectionsOnly] [/ConfigDBOnly] [/usesqlalwayson]
   

4. Run the TFSConfig RemapDBs command to redirect the cloned Azure DevOps Server to its databases.

   TFSConfig RemapDBs /DatabaseName:ServerName;DatabaseName /SQLInstances:ServerName1,erverName2 [/AnalysisInstance:ServerName] [/AnalysisDatabaseName:DatabaseName] [/review] [/continue] [/usesqlalwayson]
   

Configure the application-tier server

1. From the administration console for Azure DevOps Server, choose Configure Installed Features to launch the configuration center.

2. Launch the Application-Tier Only wizard, and in Databases, specify the new SQL Server instance where you restored the Azure DevOps Server databases. Choose the Tfs_Configuration database from the list.

   

3. Before you close the final page of the wizard, look for the “i” symbol. It signifies information that you might want for future reference. The final page also includes the location of the configuration log.

   

Update Azure DevOps Server URLs

1. Go to the application-tier node and look at the notification and the web portal URLs. Note that they still point to the location of the old deployment. Update them.

   

2. After updating the URLs with the name of the new server, review the information to make sure that it is correct.

   

Update all service accounts

You must update the service account for Azure DevOps Server (TFSService) and the data sources account (TFSReports). Even if these accounts have not changed, you must update the information to help ensure that the identity and the format of the accounts are appropriate for the new server.

1. Open a Command Prompt window as an administrator and change directories to Drive:\%programfiles%\TFS 12.0\Tools.

2. At the command prompt, type the following command to add the service account for Azure DevOps, where DatabaseName is the name of the configuration database (by default, TFS_Configuration):

   TfsConfig Accounts /add /AccountType:ApplicationTier /account: AccountName /SQLInstance: ServerName /DatabaseName: DatabaseName

3. At the command prompt, type the following command to add the data sources account:

   TfsConfig Accounts /add /AccountType:ReportingDataSource /account: AccountName /SQLInstance:ServerName /DatabaseName:DatabaseName

   For more information, see Accounts Command.

Update build servers

Now you'll need to redirect your build servers to point to the moved Azure DevOps Server deployment.

1. On each build server, open the administration console and stop the build service.

2. In the properties for the build service, update the communications properties.

   

Configure Reporting and Analysis Services

If your deployment uses a report server, you must redirect Azure DevOps Server to its location, restart the warehouse, and manually rebuild the database for Analysis Services. If you don't use reporting, skip this procedure.

1. Go to the Reporting node. The listed report server values are the old ones, not the new, so edit them.

   

2. Change the values on all three tabs to point to the new server. Make sure that you provide the correct information for the data sources account in the new deployment.

3. Choose Start Jobs to restart reporting.

4. Choose Start Rebuild to rebuild the warehouse.

Verify permissions for users, groups, and service accounts

After you move to new hardware, make sure that all users, groups, and service accounts for your deployment are configured with the permissions that they require to function correctly on each server. Some permissions, such as additional permissions in SQL Server or on the local computer, cannot be automatically migrated. For example, Azure DevOps administrators must be members of the local Administrators group on the application-tier server to open the administration console, so you must add manually them to that group.

• Log on to the server and make sure that users, groups, and service accounts are configured with the permissions required for operation. Manually spot-check membership in project groups and teams, and verify that those groups and teams have the permissions you expect.

• Browse to a project collection and make sure that all projects in that collection appear as expected, and that users in those projects can appropriately access their work items.

• Open the web portal and verify that team sites and teams appear as expected.

Not sure what groups and permissions to expect? For more information, see Add users to projects, Set administrator permissions for project collections, Set administrator permissions for Azure DevOps Server, and Service accounts and dependencies in Azure DevOps Server.

Refresh the data cache on client computers

• Log on to the server and use the ClientService Web service to force clients to update the cache for tracking work items and for Azure DevOps version control.

  http://ServerName:8080/tfs/WorkItemTracking/v3.0/ClientService.asmx
  

  For more information, see Refresh the data caches on client computers.

  If you want to refresh the entire cache for all users the next time they log on, use the witadmin rebuildcache command.

  Note

  If you restored your databases to a different point in time, you will also need to refresh the version control cache as documented in Refresh the data caches on client computers.

Notify users

Now that you've moved Azure DevOps Server, you'll need to tell your users how to connect to the moved deployment. Specifically, you'll need to give them the following information:

• The name of the new server and the URL for the web portal, so that they can reconnect to their projects

• The new database names for reporting, if reporting is part of your deployment

• If they are members of a project that uses Git, instructions for how to update every clone they have locally for every repository for that project. Specifically, they will have to run the following command for every clone:

  git remote set-url <remote name> <new URL>
  

  Users can see what the URL is for each clone by browsing the project from the Explorer tab.

  

Configure backups

Although you had backups scheduled for your old deployment, those scheduled backups weren't changed to back up your moved deployment. You'll need to configure them.

• In the administration console, go to the Scheduled Backups node and reconfigure the scheduled backups to back up the Azure DevOps Server databases on the new server. For more information, see Create a backup schedule and plan.

Q & A

Q: I want to change domains, not physical servers. Can I do that?

A: Yes. That's called an environment-based move, and the steps can be found here. You should not try to combine an environment-based move with a hardware-based move. First complete the hardware move, and then change the environment.

Q: I just realized that I want to keep using my old Azure DevOps Server after moving to new hardware. Can I do that?

A: Yes, but it's very important that you perform additional steps right away. Ideally, you should have performed these steps as part of the move or the cloning steps. That is the best way to avoid the risk of corruption of one or both deployments. If both servers are live, you could end up with corruption, particularly if they are pointing to the same reporting resources.

To fix this problem:

1. Run the TFSConfig PrepareClone command on the new server

2. Run the TFSConfig ChangeServerID Command on the new server

3. Run the TFSConfig RemapDBs Command on the new server

Q: I have a deployment that integrates with Project Server. Do I have to perform any extra steps to get it to work with my moved Azure DevOps Server?

A: Yes, after you complete the hardware move you'll need to use the TFSAdmin ProjectServer /RegisterPWA command with the /tfs, /force, and /pwa options to re-register Azure DevOps Server with Project Server. You can read more about Azure DevOps Server integration with Project Server here.