Move Update Service Server to Another Machine

This article describes how to move an existing Update Service server installation to another machine while keeping your packages, database and client connections intact.

At a high level, moving the server consists of:

  1. Installing a fresh Update Service server on the new machine.
  2. Carrying over the configuration from the old server's appsettings.json.
  3. Pointing the new server at the existing database.
  4. Moving package files (when using local file storage).
  5. Redirecting existing clients to the new server.
Note

Plan for some downtime during the move and avoid importing packages or generating installers on the old server once you start the migration, so that no changes are lost.

Before You Begin

  • Make sure the new machine meets the server-requirements.
  • Ensure you have network access from the new machine to the SQL Server hosting the Update Service database (or a plan to move the database as well).
  • Back up the existing database and, if you use local file storage, the file storage directory.

Step 1 - Install Update Service Server on the New Machine

Install the Update Service server on the new machine following Update Service Server Install. Use the same version as the old server to avoid unexpected database migrations during the move.

You can either:

  • Install against the existing database directly on the arguments page (choose the SQL instance and existing database), or
  • Install with a temporary local database and switch the connection string later (see Step 3).

Step 2 - Copy the Configuration File

The server configuration is stored in the appsettings.json file, located by default at:

C:\inetpub\wwwroot\Update Service Server\appsettings.json

Copy this file from the old machine and use it as the reference for configuring the new server. You can either replace the new server's appsettings.json with the old one, or copy individual settings across.

Warning

Do not blindly overwrite the new appsettings.json without reviewing it first. Paths, the database connection string and machine-specific values may need to be adjusted for the new environment. Review the settings described below before restarting the server.

The most important values to carry over are described in the following steps.

Note

The IdentityKey value under the Settings section is randomly generated during installation and does not need to be copied. The new server can keep its own IdentityKey.

Authentication and Identity Settings

If you have configured external authentication, also carry over the related settings so that login keeps working:

{
    "Settings": {
        "IdentityRequireAuthenticationOnServer": "...",
        "IdentityRequireAdministratorRoleOnServer": "...",
        "IdentityRequireAuthenticationOnClient": "...",
        "IdentityMicrosoftClientId": "...",
        "IdentityMicrosoftSecret": "...",
        "IdentityMicrosoftAuthorityEndpoint": "..."
    }
}

See Authentication in Update Service for details. Remember that the Azure AD app registration's redirect URIs must include the new server's login URL if the server URL changes.

Other Settings

Review the remaining settings in the file and copy any that you have customized, for example:

  • ServerName - a user-friendly name for the server.
  • PublicUrl - the URL clients use to connect to the server. Update this to the new server's URL if it has changed (see @server-settings-overview).
  • AzureStorageEnabled and the Azure Storage connection - if you use Azure Storage instead of local file storage (see @server-settings-storage).

For a full list of settings, see Update Service Server Settings.

Step 3 - Update the Database Connection String

Point the new server at your existing Update Service database. This can be done in two ways.

Using the server interface:

  1. Open the new server's user interface, accessible by default at http://localhost:8060.
  2. Navigate to the settings section.
  3. Click the pencil icon labeled Edit database settings.
  4. Provide the connection string for your existing database and submit.

Using the appsettings.json file:

  1. Open C:\inetpub\wwwroot\Update Service Server\appsettings.json in a text editor.

  2. Locate the ConnectionStrings property and set the Database connection string to point at your existing database:

    {
    "ConnectionStrings": {
        "Database": "Data Source=SERVER;Initial Catalog=UpdateService;Integrated Security=True;Encrypt=False;MultipleActiveResultSets=true"
    }
}

  3. Restart the Update Service Server site in Internet Information Services (IIS).

Note

When the database is on a different machine, the site must be able to authenticate to it. Use either a domain user with read/write access to the database together with Integrated Security=True, or SQL authentication by adding User ID=USERNAME;Password=PASSWORD to the connection string. See Update Service Server Install for how to specify the site user and connect to a database on a different server.

Step 4 - Move Package Files (Local Storage)

If your server uses local file storage (the default), the package files must be copied to the new machine, because they are stored on disk rather than in the database.

The file storage location is controlled by the FileStorageDir setting. To find the current location:

  • Open the server settings in the UI, or
  • Inspect the FileStorageDir setting in appsettings.json.

If FileStorageDir is not set, the default location is:

C:\ProgramData\LS Retail\GoCurrent\Server\FileStorage

To move the files:

  1. Stop the Update Service server site (or otherwise ensure no packages are being imported) on the old machine.
  2. Copy the entire contents of the file storage directory from the old machine to the new machine.
  3. Place the files in the file storage directory on the new machine. By default this is the path above; if you use a custom location, set FileStorageDir in appsettings.json on the new machine and copy the files there.
  4. Restart the Update Service Server site in IIS.
Note

If you use Azure Storage instead of local file storage, the package files live in the Azure Storage account and do not need to be copied. Simply make sure the Azure Storage settings are carried over from the old appsettings.json (see @server-settings-storage).

Step 5 - Review IIS Configuration

Some configuration lives in Internet Information Services (IIS) rather than in appsettings.json, so it is not carried over when you copy the configuration file. If the old server was customized in IIS, reapply the equivalent settings on the new machine.

Common cases to check:

  • Custom port, host name or bindings - if the old server was reachable on a port other than the default 8060, or on a specific host name, configure the matching site bindings in IIS on the new machine. Open IIS Manager, select the Update Service Server site, and use Bindings... in the Actions panel.
  • SSL certificate (HTTPS) - if the old server used HTTPS, install the SSL certificate on the new machine and add an HTTPS binding for it in IIS. See How to add SSL certificate to Update Service Server for the full procedure.
  • Site user (application pool identity) - if you changed the identity the site runs under (for example to a domain user that has access to a remote database), apply the same change on the new machine. See Update Service Server Install.

After changing the site's URL, port or protocol, update the PublicUrl setting so that generated installers and clients use the correct address (see @server-settings-overview), then restart the Update Service Server site in IIS.

Note

Changing the server's URL means existing installers contain the old address. Re-download installers from the new server after the move, and redirect existing clients as described in Step 7.

Step 6 - Verify the New Server

  1. Open the new server interface at its URL (by default http://localhost:8060).
  2. Confirm that your packages and versions appear under the management view.
  3. If you use authentication, confirm that login works.
  4. Generate or download an installer and confirm it contains the correct server URL.

Step 7 - Redirect Existing Clients

If the new server has a different URL than the old one, existing clients need to be pointed at the new URL. You have two options.

Option A: Automatic redirect (recommended)

On the old server, set the RedirectUrl setting in appsettings.json to the new server's URL:

{
    "Settings": {
        "RedirectUrl": "https://newserver.example.com"
    }
}

When a client connects to the old server, it will be redirected to the new URL and update its own settings accordingly. Keep the old server running until all clients have connected at least once and migrated. Because not all clients connect regularly, this can take some time.

Note

The RedirectUrl setting can only be set in the appsettings.json file, not through the server interface or cmdlets. See Update Service Server Settings.

Option B: Manual client update

On each client machine:

  1. Open the Update Service client application.
  2. Navigate to the Servers view.
  3. Edit the server URL to the new address and save.

Existing installers contain the old server URL, so after the move you should re-download installers from the new server to distribute the correct URL.

Step 8 - Retire the Old Server

Once you have confirmed that the new server is working and all clients have migrated to the new URL, you can safely turn off or uninstall the old Update Service server.

See Also