Quick start: your first published application

This page takes you from a freshly installed DartRelay to a Windows application running in a browser tab. It covers the setup wizard, adding your first host, publishing one application, giving someone access and signing in to the portal. Allow about half an hour, plus a host restart if the Remote Desktop Session Host role has to be installed.

Before you begin

• DartRelay is installed and running. See Installing DartRelay.
• You have your product key.
• You have a Windows host to publish from, with Remote Desktop enabled, and the username and password of a local administrator account on it.
• The DartRelay server can reach the host on TCP 3389 (Remote Desktop) and TCP 445 (file sharing). See System requirements.

Step 1: Complete the setup wizard

The first time you open the console, DartRelay runs a short setup wizard. It appears automatically and cannot be skipped, because DartRelay cannot work without the answers. It has four steps: the database, the licence, email, and the first administrator account.

1. Open the console. On the DartRelay server, browse to http://localhost:<port>/admin, using the port you chose during installation. The wizard opens.
2. Choose the database. Choose SQLite to keep everything in a file on this server with nothing to set up, which is the right choice for a single server. Choose SQL Server, MySQL or PostgreSQL to use a database server you already run, and enter its connection details. See Databases and migration.
3. Activate the licence. Enter your product key. DartRelay contacts the activation service and records the licence, including how many Relay Seats it allows. If this installation is to take its seats from another installation instead, use the option to enrol with that installation's address and enrolment token. See Licensing and Relay Seats.
4. Set up email. Enter your mail server details so DartRelay can send one-time sign-in codes, password-reset messages and administrator notifications. You can change these later. See Email delivery and templates.
5. Create the first administrator. Enter a username and a strong password. This account can do everything in the console. Keep its details safe; you will use it to sign in from now on.

When the wizard finishes you are taken to the console sign-in page. Sign in with the administrator account you just created. You see the Dashboard.

Step 2: Add a host

A host is the Windows machine your application is installed on. DartRelay needs to know its address and a management account it can use to check and prepare it.

1. Open the Hosts page. In the console, go to Catalog → Hosts and start a new host.
2. Enter the host's details. Give it a name people will recognise and enter its address (a DNS name or IP address).
3. Enter the management account. Type the username and password of a local administrator on the host. For the host's own local Administrator account, write .\Administrator; for a domain account, write DOMAIN\name.
4. Click Connect. DartRelay connects to the host and reports what it found: the Windows edition and whether the Remote Desktop Session Host role is installed. The result is saved with the host.
5. Click Create Host. The host's page opens and already shows the readiness result.

If the Session Host role is missing

A Windows Server without the Remote Desktop Session Host role allows only two connections at a time. For a quick test with one person that is enough, but for real use install the role. DartRelay can do it for you from the host's page:

1. Find the readiness panel on the host's page, under the management account.
2. Leave Let the domain's users sign in ticked if the host is in a domain. DartRelay then adds the domain's users to the host's Remote Desktop Users group, without which only administrators can sign in through Remote Desktop.
3. Decide about restarting. The role needs the host to restart before it takes effect. Tick the restart option to let DartRelay restart the host when the installation finishes, or leave it unticked and restart the host yourself at a convenient time.
4. Click Install RD Session Host role. A progress bar and an elapsed-time counter show while Windows installs the role. This takes several minutes.
5. Wait for the restart. Until the host restarts, its pages show Restart needed. After the restart, open any page that shows the host and the warning clears by itself.

Step 3: Publish an application

1. Open the Remote Apps page. Go to Catalog → Remote Apps and start a new application.
2. Choose the host you added in Step 2.
3. Pick the program. Open Browse / Add Apps and stay on the On This Host tab. Click Scan Host. DartRelay lists the programs it finds on the host, from the Start Menu and from Windows itself, using the host's management account. Tick the program you want and add it.
4. Check the name and icon. The name is what people will see on their tile. DartRelay takes the icon from the program; you can change it.
5. Choose how people log on to Windows. Under the logon choice, leave Pass-Through selected if people will sign in to the portal with their Windows or Active Directory account: DartRelay then logs them on to the host as themselves. If people will use accounts you create in DartRelay, choose Fixed Credentials and enter a Windows account on the host for them to use.
6. Choose who can see it. Under Access Control, either let all signed-in users see it, or restrict it and pick the users and groups who may. See Giving people access to resources.
7. Save. Saving publishes the application: DartRelay registers it on the host in the list of programs allowed to run remotely. There is no separate publish button. If registration could not be done, for example because the host could not be reached, an amber message says so and names the account that was tried.

Step 4: Make sure someone can sign in

People can sign in to the portal with accounts from up to three places. Choose the ones you want under Authentication → Authentication Methods:

For this first test, the simplest path is an Active Directory user with the application published using Pass-Through, or a portal account with the application published using Fixed Credentials.

Step 5: Sign in to the portal and launch

1. Open the portal. In a browser, go to http://<server>:<port>/portal (or your HTTPS address if you have set one up). Use a private browser window so you are not signed in as the administrator.
2. Sign in as the user you gave access to. My Resources shows the application's tile.
3. Click the tile. A new tab opens at the top of the page, and a moment later the application's window appears in it.
4. Use it, then close the tab. Closing the tab ends the session and releases the device's Relay Seat.

That is the whole journey. In the console, Sessions showed the session while it was open, and the audit log recorded the sign-in and the launch.

Where to go next

• Publish a full desktop or a web application: Desktops and web applications.
• Organise tiles into folders: Categories, folders and icons.
• Brand the sign-in and home pages: Themes.
• Turn on two-factor authentication: Two-factor authentication.
• Allow file transfer and printing: File transfer and Printing.

If something goes wrong

Connect reports that it could not reach the host

Check the address, that the DartRelay server can reach the host on TCP 445, and that the management account's password is right. A wrong password produces a message about the credentials rather than a general failure. If the message names both file sharing and WinRM, neither route was available; fix file sharing first. See Adding and preparing hosts.

"Connected, but the role state could not be determined"

DartRelay reached the host but could not read whether the Session Host role is present. The message is shown in orange because you still need to check: open the host and confirm the role in Server Manager, or install it from DartRelay.

Scan Host finds nothing, or not the program you want

Some programs create no Start Menu shortcut, and Server Core installations have no Start Menu at all. Add the program by typing its full path (for example C:\Program Files\Vendor\App\app.exe) instead of scanning. See Publishing applications.

Launching is refused with a licence message

An installation with no valid licence refuses every launch. Open System → Activation and check the licence is active. If every Relay Seat is in use, the message says how many are in use and how many are allowed. See Licensing and Relay Seats.

"Server refused connection" when an ordinary user launches

The host rejected the logon during the connection. The usual causes, in order:

• The user is not allowed to sign in through Remote Desktop on that host. Add them, or their group, to the host's Remote Desktop Users group. The host's page offers Let domain users sign in to do this for the host's own domain.
• The host's Remote Desktop licensing grace period has ended and it cannot obtain a licence; it then refuses everyone except administrators. The host's page shows this.
• With Fixed Credentials, the stored account's password is wrong or the account must change its password at next logon.

The tab opens but the application never appears

Check the application starts when you sign in to the host directly with the same account. A program that shows a prompt or closes straight away at start-up behaves the same way in DartRelay. See Troubleshooting.

Related pages