Installing and upgrading Lighthouse

This guide takes you from an empty Windows server and a SQL Server to a running iRonShore Lighthouse, then through upgrading it to a newer version. It is written for the newest version, and every version from 0.34.0 on installs the same way; where an older version differs, the step says so. Every setting and property is described in full in Running the server; this guide is the order to do things in.

You can start with any version, not only the newest. Customer downloads lists the versions iRonShore offers, newest first, so you can install an older one first and then practise upgrading it (see Practise: install an older version, then upgrade).

What you need

Step 1: Download the installers

Open Customer downloads and sign in with the email address iRonShore approved for you: it sends a one-time code. Each version has these files:

Copy setup.exe to the server and check it is the file iRonShore published. In PowerShell:

Get-FileHash .\Lighthouse-Setup-0.37.0-x64.exe -Algorithm SHA256

The hash must match the line for that file in SHA256SUMS.txt. Every file is also signed by iRonShore Technologies: right-click it, Properties, Digital Signatures.

Step 2: Make the service account

Lighthouse runs as one Windows account, which signs in to SQL Server and the CAs. A gMSA has no password to manage. On a computer with the Active Directory module for PowerShell, as a domain administrator:

1. Once per forest, if your domain has never had a gMSA, add the KDS root key, then wait 10 hours for every domain controller to have it:

   Get-KdsRootKey                # nothing listed: no key yet
   Add-KdsRootKey -EffectiveImmediately
   

2. A group for the servers that may use the account, with this server in it:

   New-ADGroup -Name "Lighthouse Servers" -GroupScope Global -GroupCategory Security
   Add-ADGroupMember "Lighthouse Servers" -Members "LH01$"
   

3. The account:

   New-ADServiceAccount -Name gmsa-lighthouse -DNSHostName gmsa-lighthouse.example.com `
     -PrincipalsAllowedToRetrieveManagedPassword "Lighthouse Servers" `
     -KerberosEncryptionType AES128,AES256 -Description "iRonShore Lighthouse"
   

4. On the Lighthouse server, restart it so its new group counts, then:

   Install-WindowsFeature RSAT-AD-PowerShell
   Install-ADServiceAccount gmsa-lighthouse
   Test-ADServiceAccount gmsa-lighthouse     # True
   

Rights on your CAs come later, when you add them. A domain user account, the built-in account and a server outside a domain are in The service account.

Step 3: Get the database ready

Lighthouse keeps everything in one SQL Server database (Lighthouse unless you name it otherwise). Pick one of three ways.

Way A: setup makes it (simplest). If you have dbcreator and securityadmin on SQL Server, there is nothing to do now. Setup creates the database, its tables, and a login for the service account with only db_datareader and db_datawriter, all signed in as you. No SQL password is stored anywhere. Check only that the server can reach SQL Server:

Test-NetConnection sql01.example.com -Port 1433     # TcpTestSucceeded : True

Way B: a DBA makes an empty database first. When you may not create databases or logins, a DBA runs this once in SQL Server Management Studio or sqlcmd (change the names), then you carry on as in way A:

CREATE DATABASE [Lighthouse];
GO
-- The person who runs setup: makes the tables now and at every upgrade.
CREATE LOGIN [EXAMPLE\alice] FROM WINDOWS;      -- skip if the login exists
USE [Lighthouse];
CREATE USER [EXAMPLE\alice] FOR LOGIN [EXAMPLE\alice];
ALTER ROLE db_owner ADD MEMBER [EXAMPLE\alice];
GO
-- The service account: read and write only.
USE [master];
CREATE LOGIN [EXAMPLE\gmsa-lighthouse$] FROM WINDOWS;
USE [Lighthouse];
CREATE USER [EXAMPLE\gmsa-lighthouse$] FOR LOGIN [EXAMPLE\gmsa-lighthouse$];
ALTER ROLE db_datareader ADD MEMBER [EXAMPLE\gmsa-lighthouse$];
ALTER ROLE db_datawriter ADD MEMBER [EXAMPLE\gmsa-lighthouse$];

Setup then finds the empty database, makes the tables and, as it always does, stops the service account from changing or deleting the Keeper's Log.

Way C: the DBAs make the tables too. Run setup with MIGRATE_DB=0 (Step 5), so it changes nothing in SQL Server. Then a DBA, on the Lighthouse server or any Windows computer that can reach SQL Server, runs:

"C:\Program Files\Lighthouse\lh.exe" db migrate --settings "%ProgramData%\Lighthouse\lighthouse.json" --grant EXAMPLE\gmsa-lighthouse$

It creates the database if there is none, makes or upgrades the tables, and gives the account read and write. It prints what it applied, or Database is already up to date. Start Lighthouse afterwards (Step 6).

Step 4: The HTTPS certificate and the name

1. Request a certificate for the name people will type, such as lighthouse.example.com, from your CA's web server template, and install it in the server's LocalMachine\My store with its private key. The key may stay non-exportable.
2. Add a DNS record for that name pointing at the server.
3. Check: Resolve-DnsName lighthouse.example.com gives the server's address, and the certificate shows in certlm.msc, Personal, Certificates, with a key icon.

Step 5: Run setup

On the server, double-click Lighthouse-Setup-<version>-x64.exe. It turns on the IIS features it needs and installs the Hosting Bundle (it carries both, so the server needs no internet), then opens the setup screens:

1. Database. SQL Server: the server's name, such as sql01.example.com or sql01\INSTANCE. Database: Lighthouse. Press Test connection: it signs in as you and says The database Lighthouse does not exist yet; the installer will create it (way A) or exists; the installer will upgrade it (way B, or an upgrade). If SQL Server's own certificate is not from a CA this server trusts, tick Trust the SQL Server's certificate.
2. Dashboard and sign-in. Choose From other computers: HTTPS with Windows sign-in, pick the HTTPS certificate from Step 4, and type the two groups as EXAMPLE\Lighthouse Administrators and EXAMPLE\Lighthouse Viewers. Setup looks them up in the domain.
3. Main sign-in. Windows to start with. AD FS, Entra ID, Okta or another OpenID Connect provider can be the main way in, with Windows kept as another way (see Sign-in providers).
4. How Lighthouse runs. IIS website, and Domain service account with no password to manage (gMSA) with EXAMPLE\gmsa-lighthouse$. Setup checks that this server may use it.
5. Website. The site and app pool names (Lighthouse), the host name (it starts as the certificate's name) and port 443.
6. Prerequisites. One line per check: OK, Will do (setup does it), Check (look at it, but it installs) or Fix (Next stays off until you fix it and press Check again). It covers IIS, the site name and port, the certificate, DNS, the database test, whether you may add SQL Server logins, and the firewall rule.
7. Summary. Everything about to happen. License file: the file iRonShore sent you, or leave it empty for the 30-day trial. Save answers writes the choices to a file (never a password) so the next server installs the same way: Lighthouse-Setup-<version>-x64.exe /quiet ANSWERS=lighthouse-answers.json.

Press Install. Setup installs the program to C:\Program Files\Lighthouse, writes the settings to %ProgramData%\Lighthouse\lighthouse.json, creates the database and its tables, gives the service account its login and rights, creates the IIS site and app pool, binds the certificate, opens the firewall port and starts Lighthouse. The finish screen opens the console.

What setup did is in %ProgramData%\Lighthouse\setup.log. For the full Windows Installer log, run setup with /log setup-log.txt, or the MSI with /l*v install-log.txt.

Silently, for a second server or a script, every screen is a property (all of them are in Running the server):

Lighthouse-Setup-0.37.0-x64.exe /quiet HOSTING=iis URL=https://lighthouse.example.com ^
  SIGNIN=Windows HTTPS_CERT=<thumbprint> ^
  OPERATORS="EXAMPLE\Lighthouse Administrators" VIEWERS="EXAMPLE\Lighthouse Viewers" ^
  SERVICEACCOUNT=EXAMPLE\gmsa-lighthouse$ ^
  CONNECTION="Server=sql01.example.com;Database=Lighthouse;Integrated Security=true;Encrypt=true"

Step 6: Check it works

1. From your own PC, open https://lighthouse.example.com/. Windows signs you in; your name shows at the top right.
2. The version at the foot of the page is the one you installed.
3. https://lighthouse.example.com/health answers {"status":"ok", ...}.
4. On the server, "C:\Program Files\Lighthouse\lh.exe" db migrate --settings "%ProgramData%\Lighthouse\lighthouse.json" says Database is already up to date.
5. In SQL Server, the database has its tables, and the service account's login is a member of db_datareader and db_datawriter:

   USE [Lighthouse];
   SELECT TOP 5 MigrationId FROM __EFMigrationsHistory ORDER BY MigrationId DESC;   -- the newest database changes
   

If something is wrong, see When something goes wrong.

Step 7: First steps in the console

Administrators see Suggested next steps on the Dashboard. Work down them: add your CAs, scan your network, add a template, add your teams. Each step has a guide with pictures in How-to guides, and the same guides are in the console under Help. Settings, License shows the trial's days left and takes the license file when it comes.

Outposts (optional), for networks the server cannot reach: turn them on under Settings, Features, then Add Outpost on Settings, Outposts. It gives a join code and links the Outpost MSI of the server's own version. See Outposts.

Upgrading to a newer version

The full procedure, with two or more servers and Outposts, is in Upgrading Lighthouse and Outposts. For one server:

1. Read what changed in every version between yours and the new one: whether the database changes, and whether Outposts need it.
2. Back up the database, copy-only so your regular backups are not affected, and check the backup:

   BACKUP DATABASE [Lighthouse] TO DISK = N'D:\Backup\Lighthouse-before-0.37.0.bak' WITH COPY_ONLY, CHECKSUM, COMPRESSION;
   RESTORE VERIFYONLY FROM DISK = N'D:\Backup\Lighthouse-before-0.37.0.bak' WITH CHECKSUM;
   

   SQL Server Express has no COMPRESSION; leave it out there.
3. Keep a copy of %ProgramData%\Lighthouse\lighthouse.json.
4. Run the new setup.exe on the server, by double-clicking it or with /quiet. It skips the screens and keeps every setting, the service account, the IIS site, the secrets and the license. It stops Lighthouse, replaces the program, makes the database changes the new version needs, and starts Lighthouse again: usually a minute or two.
5. Check as in Step 6: the new version at the foot of the page, /health answers, and lh db migrate says the database is up to date.
6. Outposts, if the new version's notes say they need it: run the new Outpost MSI on each Outpost computer. No join code is needed.

You can go straight from any version to any newer one: setup makes every database change in between, in order. You do not need to install each version on the way.

Going back. If the new version made no database change, uninstall it and install the previous version. If it did, stop Lighthouse, restore the backup from step 2, then install the previous version. Step by step in Going back.

Practise: install an older version, then upgrade

To see the whole life of a server before you install the real one, use a trial server and its own database, so nothing you run today is touched. One Windows server holds one Lighthouse server, and installing another version on it upgrades it, so a trial needs its own server (a new virtual machine is ideal).

1. A trial server and database. A new Windows Server VM in your domain, and a database name of its own, such as LighthouseTrial, on your SQL Server or on SQL Server Express on the VM itself.
2. The account. Add the VM to the gMSA's group (Step 2) and restart it, or use the built-in account for the trial.
3. Install the older version. Download, for example, 0.34.0 and follow Steps 3 to 6 with the database LighthouseTrial. Test connection says the installer will create it. Check that the foot of the page says 0.34.0.
4. Give it something to keep. Run a scan of a few of your own servers, or add a CA with Test connection, so you can see your data survive each upgrade.
5. Upgrade with a database change. Back up LighthouseTrial (Upgrading, step 2), then run 0.35.0's setup.exe. The foot of the page says 0.35.0, your data is there, and __EFMigrationsHistory has a new row for the version's database change (KeepOutCertificates for 0.35.0).
6. Upgrade with no database change. Run 0.36.0's setup.exe (0.36.0 and 0.37.0 change nothing in the database), and check again. Or jump straight to the newest version: setup makes every change in between.
7. Practise going back. From the newest version, uninstall, restore the backup taken before the last upgrade that changed the database, and install that earlier version again.
8. Clean up. Uninstall Lighthouse from the VM (Apps), drop LighthouseTrial and remove the VM from the gMSA's group.

Which versions change the database and which need Outposts is in the release notes for each version. Up to 0.37.0:

Uninstalling

Apps, iRonShore Lighthouse, Uninstall, or msiexec /x Lighthouse-<version>-x64.msi. It removes the program, the service or IIS site and app pool, and the firewall rule. The settings file, the secrets in %ProgramData%\Lighthouse and the database are kept, so installing again picks up where it left off. To remove everything, also delete %ProgramData%\Lighthouse and drop the database.

When something goes wrong

More errors, with the service account and SQL Server, are in The service account.