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

The database contains 6 application roles:

Role	Purpose
CONFIGURATOR	System configuration access
READER	Read-only access to documents
REVIEWER	Review and comment on documents
CONTROLLER	Control document workflows
EDITOR	Edit and modify documents
AUTHORISER	Authorize and approve documents

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 > Static Content
   • Web Server > Common HTTP Features > Default Document
   • 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	e.g. ELYSE-SQL01 or sql01.yourdomain.com
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: 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 5: CREATE IIS APPLICATION POOL

1. Open IIS Manager (search for IIS or run inetmgr).
2. In the left panel, click Application Pools.
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: yourdomain\svc_elyse_be and the account password.
   4. Click OK on all dialogs.

STEP 6: CREATE IIS WEBSITE

1. In IIS Manager (still open from Step 5), 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 PowerShell as Administrator and run:

   Set-WebConfigurationProperty -pspath 'MACHINE/WEBROOT/APPHOST/ElyseBackend' `
       -filter "system.webServer/security/authentication/windowsAuthentication" `
       -name "useAppPoolCredentials" -value "True"

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 (not on the server itself) 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.
   If the browser prompts for credentials: This indicates a Kerberos configuration issue. Check: (1) you are using a hostname, not localhost or an IP address; (2) HTTP SPNs are registered for the hostname (see KCD Configuration); (3) useAppPoolCredentials is set to true (Step 7 above); (4) 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

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

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.