Installing DartRelay

This page walks you through the DartRelay installer: what it asks, what each answer means, and what it does to the server. At the end you will have DartRelay running and ready for the setup wizard described in Quick start: your first published application.

Before you begin

• Check the machine meets System requirements.
• Sign in to the machine with an account that is a local administrator. The installer asks for permission to make changes when it starts.
• Decide which port the portal and console will use. If something else on the machine already uses it (for example another web server on port 80 or 443), choose a different one.
• Have your product key ready, or, if this server is joining an existing installation or using another installation's licence, have the token from that installation ready (see The licensing question).

The licensing question

The most important question the installer asks is How is this server licensed? It has three answers, and the right one depends on whether this is your first DartRelay server.

If you are unsure, choose A new installation. An installation set up as new can later be switched to use another installation's licence from its Activation page, without reinstalling.

Installing a new installation

1. Run the installer as an administrator. Accept the Windows prompt asking whether to allow it to make changes.
2. Read the welcome page. On a machine without DartRelay it describes a new installation. If it says it will upgrade an existing installation instead, stop and read Upgrading DartRelay.
3. Accept the licence agreement. This is the agreement between your organisation and Dart Innovations for the software. (It is not the same thing as the Agreements you can show your own users in the portal.)
4. Choose the installation folder. Accept the suggested folder unless you have a reason to change it. DartRelay keeps its data in the App_Data folder inside this folder, so note where it is.
5. Choose the port. Enter the port the portal and console will listen on. This is the port people will browse to, and the one to open in any firewall between your users and this server.
6. Answer the licensing question with A new installation. You will enter the product key later, in the setup wizard.
7. Check the summary and install. The Ready page lists your choices, including the port. Click Install and wait for the files to be copied and the services to start.
8. Finish. When the installer closes, DartRelay is running. Open a browser on this machine and go to http://localhost:<port>/admin, using the port you chose. The setup wizard opens. Continue with Quick start: your first published application.

Adding a server to an existing installation (joining a pool)

Use this when you already have a DartRelay installation and want another server to share its database and settings behind a load balancer. The new server becomes another member of the same installation: same resources, same users, same themes, same licence.

Before you join

• The existing installation must use a database server (SQL Server, MySQL or PostgreSQL) that the new server can reach. Servers in a pool share one database, which a SQLite file on one machine cannot do.
• Both servers must run the same version of DartRelay. Use the same installer you last installed or upgraded with.
• Obtain a join token from the existing installation's console. A token can be used once and expires after 24 hours. The setup of pools, including where to issue the token, is covered in Running several servers (pools).
• The new server must be able to reach the existing installation's web address. Use HTTPS with a trusted certificate, or keep both servers on a private network.

Steps

1. Run the installer on the new server and work through the welcome, agreement, folder and port pages as for a new installation.
2. Choose Another server for an existing installation (join a pool). The installer asks for the existing installation's address and the join token.
3. Let the installer check the token. It checks the token with the existing installation before anything is installed, so a mistyped or expired token is reported immediately rather than after the files are copied.
4. Install. No product key is asked for. When the installer finishes, the new server is using the shared database and the existing installation's licence.
5. Add the server to your load balancer. See Running several servers (pools) and Load balancer and ADC integration.

Using another installation's licence

Choose A separate installation that uses another installation's licence when this server should be a complete installation in its own right, with its own database, users and settings, but take its Relay Seats from another installation that holds the product key. A common example is an organisation with several sites in separate networks or domains that want one shared pool of seats.

1. On the installation that holds the key, switch sharing on and add an installation, which gives you an enrolment token. See Sharing one licence between installations.
2. Run the installer on the new server and choose A separate installation that uses another installation's licence.
3. Enter the key-holding installation's address and the enrolment token. The installer checks the token before installing anything.
4. Install, then complete the setup wizard on the new server as for a new installation. Within a minute of the service starting, its Activation page reports that it is licensed by another installation.

What the installer does to the server

• Copies DartRelay into the installation folder.
• Creates the data folder, App_Data, inside the installation folder, and locks it so only the local system account and Administrators can read it. This folder holds the server configuration file, the SQLite database if you use one, logs, and the keys used to encrypt stored passwords. After setting the permissions the installer reads them back, and if any file has been left unreadable it repairs the permissions automatically.
• Installs DartRelay as Windows services that start automatically with Windows and run as the local system account.
• Configures the port you chose. On first start, DartRelay records it as its first endpoint, which you can later manage under System → Endpoints. See Endpoints and certificates.
• Includes the licence texts for DartRelay and the third-party components it uses, in the installation folder.

Nothing is installed on your hosts, now or later.

After installing

1. Open http://localhost:<port>/admin on the server and complete the setup wizard: database, licence, email and the first administrator account. See Quick start.
2. Give DartRelay a proper address and an HTTPS certificate before opening it to users. See Endpoints and certificates.
3. Open the port in the firewall for the people who need it, and only them. You can also restrict the portal and the console to chosen network addresses; see Sign-in protection.

If something goes wrong

The browser cannot reach the console after installing

• Check you are using the port you chose, and http:// rather than https://: a new installation has no certificate yet.
• From another machine, check that a firewall on the server allows the port.
• If another program was already using the port, DartRelay cannot listen on it. Run the installer again and choose a free port.

The join token or enrolment token is refused

• Tokens can be used once and expire after 24 hours. Issue a new one.
• Copy the whole token, including every group. A token with part missing is refused.
• Check the address you entered is the existing installation's web address and that this server can reach it.

The services will not start

The most common cause is that the files in the App_Data folder cannot be read by the service. The installer checks for this and repairs it, and writes what it did to its setup log, including the commands to run if the repair did not succeed. You can also reset the permissions yourself from an elevated PowerShell window, replacing the path with your own 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

The first command takes ownership for the Administrators group, the second resets each file's permissions, and the third grants full control to the system account and Administrators only.

Related pages