Upgrading DartRelay

Upgrading DartRelay means running the installer for the new version on a server that already has DartRelay. Your database, users, published resources, themes and settings are kept. This page explains how to plan an upgrade, the steps, what changes on the first start, and how to upgrade several servers in a pool.

What an upgrade keeps, and what it does not

The installer recognises an existing installation and upgrades it in place. It replaces DartRelay's program files and leaves your data alone.

Database changes needed by the new version are applied automatically the first time it starts. There is nothing to run by hand.

Plan the upgrade

1. Read the release notes for the new version, for anything that changes behaviour you rely on.
2. Back up. Copy the whole App_Data folder from the installation folder to somewhere safe. If you use SQL Server, MySQL or PostgreSQL, take a backup of the DartRelay database with your usual database tools as well. The upgrade is designed to keep your data, but a backup costs minutes and protects you from anything unexpected.
3. Choose a time when nobody needs to work, or post an Announcement giving the time.
4. If you run a pool, plan to upgrade every server in the same window. See Upgrading a pool.

Steps

1. Sign in to the DartRelay server as a local administrator.
2. Optionally, check who is connected. In the console, Sessions shows the sessions that will end.
3. Run the new installer as an administrator.
4. Read the welcome page. It says that it will upgrade the existing installation and, where it can, names the version you have now. If it describes a new installation instead, cancel: you are not on the server you think you are, or DartRelay was installed differently.
5. Accept the licence agreement and continue through the remaining pages. The installation keeps its licence, folder and port.
6. Check the Ready page. It repeats that an upgrade ends open sessions and that your database, users, published applications and branding are kept. Click Install.
7. Wait. The installer stops the services, replaces the files, checks the permissions on the App_Data folder and starts the services again.
8. Finish, then open the console in a browser and sign in.

After the upgrade

Take five minutes to check the installation is healthy:

1. Sign in to the console. If a strip appears across the top about the licence, read it: it means the licence needs attention (see Licensing and Relay Seats).
2. Open Catalog → Hosts and check your hosts still show as ready.
3. Sign in to the portal as an ordinary user and open one application.
4. Read the release notes' list of changes and try anything new you plan to use.

Things that happen once, on the first start of a new version

Some upgrades carry older settings forward into newer places. These happen automatically, once:

• Load balancer settings move into the console. From version 1.9, settings such as trusted proxies, the public URL and sign-in by header are kept in the console under System → Load balancer, shared by every server. On the first start after upgrading, any of these found in dartrelay.config.json are copied into the console and removed from the file, and a dated backup copy of the file (.bak) is left beside it. A value that differs from what the console already holds stays in the file, where it overrides the console, and the log says so. See Server configuration file.
• Automatic launch rules start on "No rule" for each address. From version 1.9, where a launch rule applies is chosen on each address's Tenancy & Branding binding, and every binding starts on No rule, including after an upgrade. If you used automatic launch before, choose the rule again for each address. See Automatic launch and single-application portals.

When upgrading to version 2.0 New in 2.0

• Your Active Directory domain appears in the Directories list. Version 2.0 lists the domains people sign in from under Directories. The domain the server is joined to, and any single domain you had configured before, are added to the list automatically, and the configured one becomes the default for usernames typed without a domain. See Active Directory and multiple domains.

Upgrading a pool

Every server in a pool shares one database, and every server must run the same version. Upgrade all of them in the same maintenance window, one after another, and do not leave the pool running with mixed versions.

1. Back up the shared database and each server's App_Data folder.
2. Take the first server out of the load balancer. Drain it so no new sessions land on it (see Running several servers (pools)), and wait for its sessions to finish or tell those users.
3. Run the installer on that server, as above.
4. Upgrade the remaining servers the same way, one at a time.
5. Return every server to the load balancer and check a sign-in and a launch through the load balancer address.

Installations that share a licence

Separate installations that take their seats from another installation's licence are upgraded individually, each with its own installer run. While the key-holding installation is being upgraded, the others keep running on the allowance they already hold. See Sharing one licence between installations.

If something goes wrong

The services will not start after the upgrade

The most likely cause is that files in the App_Data folder have been left with permissions the service cannot read. The installer checks every file after an upgrade and repairs this automatically, writing what it found to its setup log. If the services still do not start, reset the permissions from an elevated PowerShell window, replacing the path with your installation folder:

takeown /F "C:\Path\To\DartRelay\App_Data" /R /D Y /A
icacls  "C:\Path\To\DartRelay\App_Data" /reset /T /C
icacls  "C:\Path\To\DartRelay\App_Data" /grant "*S-1-5-18:(OI)(CI)F" "*S-1-5-32-544:(OI)(CI)F" /T /C

Afterwards, each file in the folder should list exactly two entries, both inherited: NT AUTHORITY\SYSTEM and BUILTIN\Administrators. You can check one with icacls "C:\Path\To\DartRelay\App_Data\<file>".

The setup wizard appears instead of the console

DartRelay could not find its database. Do not complete the wizard. Check that the App_Data folder is still present and readable, and, for a database server, that the server is reachable. If the folder has been lost, restore it from your backup.

A load balancer setting does not seem to apply

If System → Load balancer shows a field as set on this server, a value in that server's dartrelay.config.json is overriding the console. Remove it from the file to let the console's value apply. See Server configuration file.

Users report automatic launch stopped working

After upgrading to 1.9 or later from an earlier version, choose the launch rule again on each address's binding, as described above.

Related pages