Backend Installation (Server / Domain)

OVERVIEW

This page covers the installation of the Elyse .NET backend for SERVER deployments — multi-user environments with Active Directory and Kerberos Constrained Delegation (KCD).

The backend is a framework-dependent ASP.NET Core application hosted in IIS. It requires the .NET 8.0 Runtime on the server.

• For workgroup (single-user, no domain) deployments, see Backend Installation (Workgroup).
• For the frontend installation, see Frontend Installation.

PREREQUISITES

Before starting, ensure the following are complete:

On this backend server:

• Windows Server 2016 or later
• Server is joined to the Active Directory domain

Completed on other servers (prior steps):

• Service account svc_elyse_be created on the Domain Controller per Domain Setup
• KCD configured on the Domain Controller per KCD Configuration
• SQL Server installed on the database server, database restored, and permissions configured per SQL Server & Database

PACKAGE CONTENTS

The backend deployment package (Elyse-Backend-*-SERVER-*.zip) contains:

File	Description
elyse_asp-backend.dll	Main application assembly
elyse_asp-backend.exe	Small launcher (~148 KB)
web.config	IIS configuration
.env.template	Configuration template
SERVER_README.txt	Quick offline reference
RELEASE_NOTES.txt	Release notes for this version
VERSION-BACKEND.txt	Version identifier
Supporting DLLs	~28 MB total

SECURITY ARCHITECTURE

Elyse uses SQL Server application roles for ALL data access permissions. Individual users and the application service account have NO direct permissions.

• Users connect via an AD security group (Elyse_Users) with CONNECT permission only
• The IIS application pool identity (service account) must NEVER have a SQL Server login or be a member of the Elyse_Users AD group
• All data access is through application roles activated by sp_setapprole
• All connections are made as the authenticated user via KCD impersonation

STEP 1: INSTALL PREREQUISITES

IIS and the .NET 8.0 Hosting Bundle must be installed on this backend server before proceeding.

1a. Install IIS with Windows Authentication

1. Open Server Manager.
2. Click Manage (top-right menu) → Add Roles and Features.
3. The “Add Roles and Features Wizard” opens. Click Next on each page until you reach the Server Roles page.
4. Check Web Server (IIS). Click “Add Features” when prompted.
5. Click Next until you reach the Role Services page.
6. Ensure the following are checked (expand each section to find them):
   • Web Server > Common HTTP Features > Default Document
   • Web Server > Common HTTP Features > Static Content
   • Web Server > Security > Windows Authentication
   • Management Tools > IIS Management Console
7. Click Next, then Install. Wait for the installation to complete.

Verify: Open a web browser on the server and navigate to http://localhost. You should see the default IIS welcome page (a blue page with the IIS logo). This confirms IIS is installed and the C:\inetpub\wwwroot\ directory now exists.

1b. Install the .NET 8.0 Hosting Bundle

The ASP.NET Core Hosting Bundle installs the .NET 8.0 Runtime and the ASP.NET Core IIS module, which allows IIS to host .NET applications.

1. On a machine with internet access, go to https://dotnet.microsoft.com/en-us/download/dotnet/8.0
2. Under ASP.NET Core Runtime 8.0.x, find the Hosting Bundle download link (Windows). Download the installer. The file will be named something like dotnet-hosting-8.0.x-win.exe.
3. If the backend server has no internet access, copy the installer to the server (e.g., via USB or file share).
4. Double-click the installer on the backend server. Accept the license terms and click Install. Wait for completion, then click Close.

STEP 2: COPY FILES TO SERVER

1. Locate the backend deployment package file (Elyse-Backend-*-SERVER-*.zip) that you downloaded.
2. Right-click the zip file and select Extract All...
3. Choose a temporary extraction location (e.g., C:\Temp\ElyseBackend) and click Extract.
4. Create the deployment directory. In File Explorer, navigate to C:\inetpub\wwwroot\, then:
   1. Right-click in the empty space of the right panel and select New > Folder.
   2. Name the folder Elyse and press Enter.
   3. Double-click the Elyse folder to open it.
   4. Right-click in the empty space again and select New > Folder.
   5. Name the folder backend and press Enter.

   The full path should be: C:\inetpub\wwwroot\Elyse\backend

5. Open a second File Explorer window and navigate to the temporary extraction folder (e.g., C:\Temp\ElyseBackend).
6. Select all files in the extracted folder (press Ctrl+A), then right-click and select Copy (or press Ctrl+C).
7. Switch to the first File Explorer window showing C:\inetpub\wwwroot\Elyse\backend, right-click in the empty space, and select Paste (or press Ctrl+V).
8. Verify the directory contains elyse_asp-backend.dll, elyse_asp-backend.exe, web.config, and .env.template.

STEP 3: CONFIGURE THE .ENV FILE

The .env file contains all runtime configuration. Create it from the template:

1. In File Explorer, navigate to C:\inetpub\wwwroot\Elyse\backend\
2. Locate the file .env.template. Right-click it and select Copy. Then right-click in the empty space and select Paste. This creates a file called .env.template - Copy.
3. Right-click the copied file (.env.template - Copy) and select Rename. Change the name to .env (just a dot followed by env, with no other extension). Press Enter. If Windows warns about changing the file extension, click Yes.
   Note: If you cannot see file extensions in File Explorer, click the View tab in the File Explorer ribbon and check File name extensions. This ensures you can see and edit the full filename including the extension.
4. Right-click the .env file and select Open with > Notepad (or another text editor). If “Open with” is not visible, select Open with > Choose another app, then select Notepad.
5. Edit the following settings (each setting is on its own line in the format SETTING_NAME=value):

Setting	Value	Notes
DB_HOST	Your SQL Server hostname	See note above
DB_NAME	Elyse_DB	Default database name
USE_KCD	true	Must be true for SERVER deployments
SERVER_URLS	http://localhost:5000	Keep as localhost for IIS reverse proxy

Configure the application role passwords (must match the passwords set in SQL Server):

CONFIGURATOR_PASSWORD=actual_password
READER_PASSWORD=actual_password
REVIEWER_PASSWORD=actual_password
CONTROLLER_PASSWORD=actual_password
EDITOR_PASSWORD=actual_password
AUTHORISER_PASSWORD=actual_password

STEP 4: CREATE IIS APPLICATION POOL

1. Open IIS Manager (search for IIS or run inetmgr).
2. In the left panel (called “Connections”), you should see your server name (e.g., ELYSE-BE01). If there is a + arrow next to it, click the arrow to expand it. Then click Application Pools to select it.
3. In the Actions panel (right), click Add Application Pool.
4. Configure:

   Setting	Value
   Name	ElyseAppPool
   .NET CLR version	No Managed Code
   Managed pipeline mode	Integrated

5. Click OK.
6. In the centre panel, you should now see the new ElyseAppPool listed. Click on it to select it.
7. In the Actions panel (right side), click Advanced Settings...
8. In the Advanced Settings dialog, scroll down to the Process Model section. Set Identity to the backend service account:
   1. Click the Identity row (it will show ApplicationPoolIdentity by default), then click the small [...] button that appears on the right side of the row.
   2. Select Custom account and click Set.
   3. Enter the domain and service account username: YOURDOMAIN\svc_elyse_be (e.g., ELYSE\svc_elyse_be for the domain-in-a-box lab), and the account password.
   4. Click OK on all dialogs.

STEP 5: SECURE THE .ENV FILE

The .env file contains application role passwords and must be secured.

Open PowerShell as Administrator (right-click Windows PowerShell and select Run as administrator). Type or paste the following commands and press Enter after each one:

$envFile = "C:\inetpub\wwwroot\Elyse\backend\.env"

# Remove inherited permissions
icacls $envFile /inheritance:r

# Grant access only to SYSTEM, Administrators, and the App Pool identity
icacls $envFile /grant "NT AUTHORITY\SYSTEM:(R)"
icacls $envFile /grant "BUILTIN\Administrators:(R)"
icacls $envFile /grant "IIS AppPool\ElyseAppPool:(R)"

# Verify permissions
icacls $envFile

The output should show only SYSTEM, Administrators, and the application pool identity.

STEP 6: CREATE IIS WEBSITE

1. In IIS Manager (still open from Step 4), look at the left panel (called “Connections”). Click the + arrow next to the server name to expand it.
2. Right-click Sites and select Add Website...
3. Configure:

   Setting	Value
   Site name	ElyseBackend
   Application pool	ElyseAppPool
   Physical path	C:\inetpub\wwwroot\Elyse\backend
   Binding – Type	http
   Binding – Port	5000

4. Click OK.

STEP 7: CONFIGURE WINDOWS AUTHENTICATION

1. In IIS Manager (still open from Step 6), click on the ElyseBackend site in the left panel under Sites to select it.
2. In the centre panel (called “Features View”), locate and double-click the Authentication icon. (If you see a list of files instead of icons, click Features View at the bottom of the centre panel to switch views.)
3. You will see a list of authentication methods. Right-click Windows Authentication and select Enable. (If it already shows “Enabled” in the Status column, no action is needed.)
4. Right-click Anonymous Authentication and select Disable. (If it already shows “Disabled” in the Status column, no action is needed.)
5. Configure Windows Authentication to use the application pool identity for Kerberos ticket decryption. Open Command Prompt as Administrator (right-click Command Prompt and select Run as administrator). Type or paste the following commands and press Enter after each one:

   C:\Windows\System32\inetsrv\appcmd.exe unlock config -section:system.webServer/security/authentication/windowsAuthentication
   
   C:\Windows\System32\inetsrv\appcmd.exe set config "ElyseBackend" -section:system.webServer/security/authentication/windowsAuthentication /useAppPoolCredentials:true /commit:apphost

   The first command unlocks the windowsAuthentication section. The second command sets useAppPoolCredentials to true for the ElyseBackend site.

STEP 8: START AND TEST

1. In IIS Manager (still open from Step 7), click Application Pools in the left panel. Click on ElyseAppPool in the centre panel to select it. In the Actions panel (right side), click Start if the pool is not already running. (If the Start option is greyed out, the pool is already running.)
2. Wait 5–10 seconds for the application to initialise.
3. Browser test. Open a web browser on a domain-joined workstation logged in as a domain user (not on the server itself, and not as a local Administrator account) and navigate to http://ELYSE-BE01:5000/api/eula/read (replace ELYSE-BE01 with your backend hostname). The browser should not prompt for credentials — authentication should be completely transparent. You should see JSON data appear automatically.
   Domain-in-a-box lab: This browser test requires a domain user account. If you are following the Domain-in-a-Box guide, test user accounts are created in Step 29. You can skip this browser test for now and use the PowerShell test (Step 8.4 below) instead, then return to this browser test after creating test users.
   If the browser prompts for credentials: This indicates a Kerberos configuration issue. Check: (1) you are logged in as a domain user, not a local Administrator account; (2) you are using a hostname, not localhost or an IP address; (3) HTTP SPNs are registered for the hostname (see KCD Configuration); (4) useAppPoolCredentials is set to true (Step 7 above); (5) the URL is in the browser’s Local Intranet zone.
4. PowerShell test (alternative). Open PowerShell and type or paste the following command and press Enter:

   Invoke-WebRequest -Uri 'http://localhost:5000/api/eula/read' -UseDefaultCredentials

   Expected result: StatusCode = 200

   Understanding the PowerShell test results:

   • If you get "Login failed for user 'DOMAIN\username'": This error message actually confirms that Kerberos Constrained Delegation (KCD) is working correctly. The backend successfully impersonated your Windows account and passed your credentials to SQL Server. The login failed because your account is not in the Elyse_Users security group. This is expected behavior — only authorized users should have database access.
   • If KCD was NOT working: You would see a different error like "Login failed for user 'DOMAIN\svc_elyse_be'" (the service account name instead of your username). This would indicate the backend is using its own service account credentials instead of impersonating you.
   • For a successful test: The user account running the PowerShell command must be a member of the Elyse_Users security group in Active Directory. In a domain-in-a-box lab environment, test user accounts are created later in the setup process (see Domain-in-a-Box - Step 29).
   If you get a SQL Server connection error: The error message "A network-related or instance-specific error occurred while establishing a connection to SQL Server" indicates that the backend cannot reach SQL Server. Common causes:

   • SQL Server firewall not configured: Verify that Windows Firewall on the SQL Server machine allows inbound connections on port 1433. See SQL Server & Database - Step 5d for the firewall rule command.
   • Incorrect DB_HOST in .env file: Verify the DB_HOST value matches your SQL Server hostname (e.g., ELYSE-SQL01).
   • SQL Server not running: Verify the SQL Server service is running on the SQL Server machine.
5. Check the application logs for any errors:

   Get-Content C:\inetpub\wwwroot\Elyse\backend\logs\stdout*.log -Tail 50

   Look for any ERROR or CRITICAL messages.

UPDATING TO A NEW RELEASE

When a new version of Elyse is released, follow these steps to update the SERVER backend while preserving your configuration and data. Two methods are provided: a manual method using File Explorer and IIS Manager, and a PowerShell script method.

Update Prerequisites

• Download the new Elyse-Backend-*-SERVER-*.zip package
• Administrator access to the server
• Access to IIS Manager
• Note your current installation location (e.g. C:\inetpub\wwwroot\Elyse\backend)
• Note your IIS application pool name (e.g. ElyseAppPool)
• Schedule a maintenance window and notify users

Method 1 — Manual Update (File Explorer + IIS Manager)

1. Backup current version. In File Explorer, navigate to C:\inetpub\wwwroot\Elyse\. Right-click the backend folder and select Copy, then right-click in the same directory and select Paste. Windows will create backend - Copy. Rename it to backend_backup_YYYYMMDD (replacing YYYYMMDD with today’s date, e.g. backend_backup_20260415).
2. Verify .env was backed up. Open the backup folder you just created and confirm the .env file is present. If it is not, STOP and investigate — the .env file contains your configuration and passwords and must be preserved.
3. Extract the new package. Locate the new Elyse-Backend-*-SERVER-*.zip file. Right-click it and select Extract All..., choose a temporary location (e.g. C:\Temp\ElyseBackend), and click Extract.
4. Stop the application pool. Open IIS Manager (search for IIS or run inetmgr). In the left panel, click Application Pools. In the centre panel, click ElyseAppPool to select it. In the Actions panel (right side), click Stop. Wait 10 seconds for connections to close.
5. Delete old application files. In File Explorer, navigate to C:\inetpub\wwwroot\Elyse\backend\. Delete the following files (select each type, right-click, and select Delete):
   • All .dll files
   • All .exe files
   • All .json files
   • All .xml files
   • The web.config file
   Important: Do NOT delete the .env file or the logs folder. The .env file contains your configuration and passwords. The logs folder contains application logs.
   Tip: To select files by type, click the Type column header in File Explorer to sort by file type. This groups all .dll files together, all .exe files together, etc., making it easier to select and delete them.
6. Copy new files. Open a second File Explorer window and navigate to the extracted folder (e.g. C:\Temp\ElyseBackend). Press Ctrl+A to select all files, then Ctrl+C to copy. Switch to the first File Explorer window showing the backend directory and press Ctrl+V to paste. If prompted about the .env.template file, you may overwrite it (it is a template, not your configuration).
7. Verify .env file. Confirm the .env file is still present in the backend directory. Right-click it and select Open with > Notepad. Verify that DB_HOST shows your SQL Server name and USE_KCD=true is set. Close Notepad.
8. Start the application pool. In IIS Manager (still open from step 4), click Application Pools in the left panel. Click ElyseAppPool in the centre panel. In the Actions panel (right side), click Start.
9. Test. Wait 5–10 seconds, then open PowerShell and run:

   Invoke-WebRequest -Uri 'http://localhost:5000/api/eula/read' -UseDefaultCredentials

   Expected result: StatusCode = 200. If you see errors, check the logs in C:\inetpub\wwwroot\Elyse\backend\logs\.

Method 2 — PowerShell Script

Open PowerShell as Administrator (right-click Windows PowerShell and select Run as administrator). Edit the $packagePath variable to match where you extracted the new ZIP, then type or paste the following commands and press Enter:

# === EDIT THIS: Set to the folder where you extracted the new ZIP ===
$packagePath = 'C:\Temp\ElyseBackend'

cd C:\inetpub\wwwroot\Elyse

# Step 1: Backup current version
$timestamp = Get-Date -Format 'yyyyMMdd-HHmmss'
Copy-Item -Path .\backend -Destination .\backend-backup-$timestamp -Recurse

# Verify .env file was backed up
if (-not (Test-Path .\backend-backup-$timestamp\.env)) {
    Write-Host "ERROR: .env file was NOT backed up. STOP and investigate!" -ForegroundColor Red
    return
}
Write-Host "Backup created: backend-backup-$timestamp"

# Step 2: Stop IIS Application Pool
Import-Module WebAdministration
Stop-WebAppPool -Name 'ElyseAppPool'
Start-Sleep -Seconds 10

# Step 3: Delete old application files (keep .env and logs)
cd .\backend
Remove-Item *.dll -Force
Remove-Item *.exe -Force
Remove-Item *.json -Force
Remove-Item *.xml -Force
Remove-Item web.config -Force

# Step 4: Copy new files from extracted package
Copy-Item $packagePath\*.dll -Destination . -Force
Copy-Item $packagePath\*.exe -Destination . -Force
Copy-Item $packagePath\*.json -Destination . -Force
Copy-Item $packagePath\*.xml -Destination . -Force
Copy-Item $packagePath\web.config -Destination . -Force

# Step 5: Verify .env file still exists
if (-not (Test-Path .\.env)) {
    Write-Host "WARNING: .env file is missing! Restoring from backup..." -ForegroundColor Yellow
    Copy-Item ..\backend-backup-$timestamp\.env -Destination .\.env -Force
}
Get-Content .\.env | Select-String 'DB_HOST|USE_KCD'

# Step 6: Start and verify
Start-WebAppPool -Name 'ElyseAppPool'
Start-Sleep -Seconds 5
Invoke-WebRequest -Uri 'http://localhost:5000/api/eula/read' -UseDefaultCredentials
Write-Host "Update complete." -ForegroundColor Green

Cleanup Old Backups (Optional)

After confirming the update is successful, keep at least the 2–3 most recent backups and delete older ones.

In File Explorer, navigate to C:\inetpub\wwwroot\Elyse\. You will see folders named backend_backup_YYYYMMDD (or backend-backup-*). Right-click any old backup folders you no longer need and select Delete.

Or via PowerShell:

cd C:\inetpub\wwwroot\Elyse
Get-ChildItem .\backend-backup-* | Sort-Object Name -Descending | Select-Object -Skip 2 | Remove-Item -Recurse -Force

ROLLBACK PROCEDURE

If the update fails or causes problems, restore the previous version from the backup you created during the update.

Method 1 — Manual Rollback (File Explorer + IIS Manager)

1. Stop the application pool. Open IIS Manager. Click Application Pools, select ElyseAppPool, and click Stop in the Actions panel. Wait 10 seconds.
2. Delete the failed update files. In File Explorer, navigate to C:\inetpub\wwwroot\Elyse\backend\. Press Ctrl+A to select all files and folders, then press Delete. Confirm the deletion. (It is safe to delete everything here because you are about to restore from the backup.)
3. Restore from backup. Navigate to your backup folder (e.g. C:\inetpub\wwwroot\Elyse\backend_backup_20260415). Press Ctrl+A to select all files, then Ctrl+C to copy. Navigate back to the empty backend folder and press Ctrl+V to paste.
4. Start the application pool. In IIS Manager, click Application Pools, select ElyseAppPool, and click Start in the Actions panel.
5. Test. Wait 5–10 seconds, then open PowerShell and run:

   Invoke-WebRequest -Uri 'http://localhost:5000/api/eula/read' -UseDefaultCredentials

   Expected result: StatusCode = 200.

Method 2 — PowerShell Rollback

# Stop the application pool
Import-Module WebAdministration
Stop-WebAppPool -Name 'ElyseAppPool'
Start-Sleep -Seconds 10

# Navigate to parent directory
cd C:\inetpub\wwwroot\Elyse

# Remove the failed update
Remove-Item .\backend -Recurse -Force

# Restore from backup (replace with your actual backup folder name)
Copy-Item .\backend-backup-YYYYMMDD-HHMMSS -Destination .\backend -Recurse

# Start the application pool
Start-WebAppPool -Name 'ElyseAppPool'

# Verify
Start-Sleep -Seconds 5
Invoke-WebRequest -Uri 'http://localhost:5000/api/eula/read' -UseDefaultCredentials

# Check logs
Get-Content .\backend\logs\stdout*.log -Tail 50

TROUBLESHOOTING

VERIFYING USER AUTHENTICATION

Once the frontend is deployed (see Frontend Installation) and working, verify that the database is correctly resolving the connected user:

1. Open the application in your web browser.
2. Navigate to: Connected User → Who is this?
3. Check the username displayed at the right-hand end of the message bar.
4. Verify that the username matches the Windows login.

This confirms that:

• Windows Authentication is working correctly
• The backend is properly impersonating the user (KCD is functioning)
• The database is correctly resolving the user’s Windows identity
• User-level access control is functioning

NEXT STEPS

Production Deployments

1. Install the frontend application layer: Frontend Installation
2. After both layers are installed, proceed to Bootstrapping and Configuration to onboard users and configure the system.

Domain in a Box Deployments

If you are following the Domain in a Box guide, return to that guide and continue with Phase 5: Frontend Server (ELYSE-FE01) — Step 22 onwards.