Backend Installation (Read-Only)

OVERVIEW

This page covers the installation of the WORKGROUP READ ONLY backend — a special variant with all write, update, delete, and elevated-privilege endpoints removed from the code. It is designed to create a read-only, public-facing, anonymous-user interface.

The backend is a self-contained executable (~128 MB) that includes the full .NET runtime. No .NET Runtime installation is required on the target machine. It runs as a Windows Service under a dedicated service account.

• For the standard workgroup (single-user, authenticated) backend, see Backend Installation (Workgroup).
• For the server (multi-user, domain/KCD) backend, see Backend Installation (Server).
• For the frontend installation, see Frontend Installation.

KEY CHARACTERISTICS

This read-only backend is typically deployed alongside an existing SERVER or standard WORKGROUP backend, sharing the same database. All users who access the read-only interface are seen as the same service account — there is no individual user authentication.

PREREQUISITES

• Windows 10/11 or Windows Server with the database accessible via the network
• SQL Server already installed and the Elyse database restored per SQL Server & Database
• A dedicated Windows account to run the read-only service (e.g. svc_elyse_ro or a local account)
• Administrative access to PowerShell (for service creation)
• The READER application role password from your DBA

PACKAGE CONTENTS

The read-only backend deployment package (Elyse-Backend-*-WORKGROUP-READ_ONLY-*.zip) contains:

PREREQUISITE: SQL SERVER LOGIN

Before deploying the backend, a SQL Server login must be created for the dedicated service account that will run the read-only service. This account connects to SQL Server directly (not via KCD).

Create the SQL Server Login

Open SQL Server Management Studio (SSMS). In the “Connect to Server” dialog, connect to your SQL Server instance using Windows Authentication and click Connect.

Method 1 — SSMS GUI

1. In the Object Explorer panel (left side of SSMS), click the + icon next to Security to expand it.
2. Right-click Logins and select New Login...
3. In the “Login – New” dialog, click the Search... button next to the Login name field.
4. In the “Select User or Group” dialog, click Locations... and select the appropriate location (local computer or domain). Click OK.
5. Click Advanced..., then click Find Now. A list of accounts will appear. Select the read-only service account (e.g. svc_elyse_ro) from the list and click OK.
6. Click OK again. The login name should now show the service account (e.g. YOURDOMAIN\svc_elyse_ro).
7. Click OK to create the login.

Method 2 — SQL Script

Alternatively, click the New Query button in the toolbar (or press Ctrl+N). In the script below, replace COMPUTERNAME\svc_elyse_ro with the actual computer name (or domain name) and service account name before executing. Then press F5 to execute:

USE master;
GO
CREATE LOGIN [COMPUTERNAME\svc_elyse_ro] FROM WINDOWS;
GO

Grant Database Access

The service account only needs CONNECT permission. All actual data permissions come from the READER application role.

Method 1 — SSMS GUI

1. In the Object Explorer panel, click the + icon next to Databases to expand it.
2. Click the + icon next to Elyse_DB to expand it.
3. Click the + icon next to Security (under Elyse_DB, not the server-level Security).
4. Right-click Users and select New User...
5. In the “Database User – New” dialog:
   1. Set User type to Windows user (this should be the default).
   2. In the User name field, type the service account name (e.g. YOURDOMAIN\svc_elyse_ro). Or click the [...] button to search for it.
   3. The Login name field should auto-populate with the same value. If not, click the [...] button and select the login you created in the previous step.
6. Do NOT check any boxes under “Database role membership” — leave only public checked (this is the default and provides CONNECT permission).
7. Click OK to create the user.

Method 2 — SQL Script

Alternatively, click the New Query button in the toolbar (or press Ctrl+N) to open a new query editor tab. In the script below, replace COMPUTERNAME\svc_elyse_ro with the actual computer name (or domain name) and service account name before executing. Then press F5 to execute:

USE [Elyse_DB];
GO
CREATE USER [COMPUTERNAME\svc_elyse_ro] FOR LOGIN [COMPUTERNAME\svc_elyse_ro];
GO
-- User now has CONNECT permission by default
-- No additional permissions needed - sp_setapprole is automatically available

STEP 1: CREATE BACKEND DIRECTORY

Method 1 — File Explorer

1. Open File Explorer. Navigate to C:\.
2. Right-click in the empty space and select New > Folder. Name the folder ElyseReadOnly and press Enter.
3. Double-click the ElyseReadOnly folder to open it.
4. Right-click in the empty space and select New > Folder. Name the folder Backend and press Enter.
5. Double-click the Backend folder to open it.
6. Right-click in the empty space and select New > Folder. Name the folder logs and press Enter.

The full path should be: C:\ElyseReadOnly\Backend\logs.

Method 2 — PowerShell

Alternatively, open PowerShell as Administrator. Type or paste the following commands and press Enter:

$BackendPath = "C:\ElyseReadOnly\Backend"
Write-Host "Creating backend directory: $BackendPath"
New-Item -ItemType Directory -Path "$BackendPath" -Force
New-Item -ItemType Directory -Path "$BackendPath\logs" -Force

STEP 2: DEPLOY FILES

1. Locate the read-only backend deployment package file (Elyse-Backend-*-WORKGROUP-READ_ONLY-*.zip) that you downloaded.
2. Right-click the zip file and select Extract All...
3. Choose a temporary extraction location (e.g., C:\Temp\ElyseReadOnly) and click Extract.
4. Open File Explorer. Navigate to C:\ElyseReadOnly\Backend.
5. Open a second File Explorer window and navigate to the temporary extraction folder (e.g., C:\Temp\ElyseReadOnly).
6. From the extracted folder, copy elyse_asp-backend.exe and .env.template to the backend directory:
   1. Select both files (click the first file, then hold Ctrl and click the second file).
   2. Right-click and select Copy (or press Ctrl+C).
   3. Switch to the first File Explorer window showing the backend directory.
   4. Right-click in the empty space and select Paste (or press Ctrl+V).

STEP 3: CONFIGURE THE .ENV FILE

1. In File Explorer, navigate to C:\ElyseReadOnly\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 copy of the file.
3. Right-click the copied file 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.
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 name	e.g. ELYSE-SQL01 or sql01.yourdomain.com
   DB_NAME	Elyse_DB	The production database name
   USE_KCD	false	Required — KCD is not used for read-only
   SERVER_URLS	http://localhost:5001	Use port 5001 if another backend is already on 5000

6. Set the READER application role password (get this from your DBA):

   READER_PASSWORD=actual_password_here

   Note: The read-only .env.template only contains READER_PASSWORD. The other 5 role password settings (CONFIGURATOR, REVIEWER, CONTROLLER, EDITOR, AUTHORISER) are absent because the corresponding endpoints do not exist in this variant.
7. To confirm the correct DB_HOST name: open SSMS, connect to the server, then look at the server name shown at the top of the Object Explorer panel (left side). That is the value to use for DB_HOST.
8. Save the file by pressing Ctrl+S in Notepad, then close Notepad.

STEP 4: SECURE THE .ENV FILE

The .env file contains the READER application role password and must be secured.

Open PowerShell as Administrator (right-click Windows PowerShell and select Run as administrator). In the script below, you must edit the $ServiceAccount value on the second line — replace COMPUTERNAME\svc_elyse_ro with the actual computer name (or domain name) and service account name. Then type or paste the edited script and press Enter:

$BackendPath = "C:\ElyseReadOnly\Backend"
$ServiceAccount = "COMPUTERNAME\svc_elyse_ro"  # <-- EDIT THIS LINE

Write-Host "Securing .env file for service account: $ServiceAccount"

# Remove inherited permissions
icacls "$BackendPath\.env" /inheritance:r

# Grant access only to SYSTEM, Administrators, and the service account
icacls "$BackendPath\.env" /grant "NT AUTHORITY\SYSTEM:(R)"
icacls "$BackendPath\.env" /grant "BUILTIN\Administrators:(R)"
icacls "$BackendPath\.env" /grant "${ServiceAccount}:(R)"

# Verify permissions
Write-Host "Current permissions on .env file:"
icacls "$BackendPath\.env"

STEP 5: SET FOLDER PERMISSIONS

Still in the same PowerShell Administrator window. In the script below, you must edit the $ServiceAccount value on the second line — replace COMPUTERNAME\svc_elyse_ro with the same service account name you used in Step 4. Then type or paste the edited script and press Enter:

$BackendPath = "C:\ElyseReadOnly\Backend"
$ServiceAccount = "COMPUTERNAME\svc_elyse_ro"  # <-- EDIT THIS LINE

Write-Host "Setting folder permissions for service account: $ServiceAccount"

# Grant service account read/execute access to backend folder
icacls "$BackendPath" /grant "${ServiceAccount}:(OI)(CI)RX" /T

# Grant service account write access to logs folder
icacls "$BackendPath\logs" /grant "${ServiceAccount}:(OI)(CI)M" /T

Write-Host "Permissions set successfully"

STEP 6: GRANT LOG ON AS A SERVICE

The service account needs the “Log on as a service” permission before it can run a Windows Service.

Open the Local Security Policy editor (run secpol.msc as Administrator — right-click and select Run as administrator).

In the Local Security Policy window:

1. In the left panel, click the + arrow next to Local Policies to expand it.
2. Click User Rights Assignment.
3. In the right panel, scroll down and double-click Log on as a service.
4. In the “Log on as a service Properties” dialog, click the Add User or Group... button.
5. In the “Select Users or Groups” dialog, click Advanced...
6. Click Find Now. A list of users and groups will appear.
7. Select the service account (e.g. svc_elyse_ro) from the list.
8. Click OK to close the search results.
9. Click OK to add the user.
10. Click OK to close the Properties dialog.
11. Close the Local Security Policy window.

STEP 7: CREATE WINDOWS SERVICE

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

sc.exe stop ElyseBackendReadOnly
sc.exe delete ElyseBackendReadOnly

The script below will prompt you for the service account name and password. Edit the $BackendPath variable if you used a different installation directory.

# Edit this if you used a different installation directory
$BackendPath = "C:\ElyseReadOnly\Backend"
$ServiceName = "ElyseBackendReadOnly"
$ExePath = "$BackendPath\elyse_asp-backend.exe"

# Verify the executable exists
if (-not (Test-Path $ExePath)) {
    Write-Host "ERROR: $ExePath not found. Check Step 2." -ForegroundColor Red
    return
}

# Prompt for the service account
$ServiceUser = Read-Host "Enter the service account (e.g. COMPUTERNAME\svc_elyse_ro or DOMAIN\svc_elyse_ro)"

Write-Host ""
Write-Host "Backend path    : $BackendPath"
Write-Host "Executable      : $ExePath"
Write-Host "Service account : $ServiceUser"
Write-Host ""

# Prompt for the service account password (masked input)
$SecurePassword = Read-Host "Enter the password for $ServiceUser" -AsSecureString
$BSTR = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($SecurePassword)
$PlainPassword = [System.Runtime.InteropServices.Marshal]::PtrToStringAuto($BSTR)

# Create the service
sc.exe create $ServiceName binPath= "$ExePath" start= auto

# Configure service to run as the specified service account
sc.exe config $ServiceName obj= "$ServiceUser" password= "$PlainPassword"

# Clear the password from memory
$PlainPassword = $null
[System.Runtime.InteropServices.Marshal]::ZeroFreeBSTR($BSTR)

# Set service description
sc.exe description $ServiceName "Elyse Document Management System - Read-Only Backend API"

# Configure automatic restart on failure
sc.exe failure $ServiceName reset= 86400 actions= restart/60000/restart/60000/restart/60000

Write-Host ""
Write-Host "Service created successfully." -ForegroundColor Green

Expected output: [SC] CreateService SUCCESS and [SC] ChangeServiceConfig SUCCESS.

STEP 8: START THE SERVICE

Method 1 — Services GUI

1. Open the Services application: press the Windows key, type services.msc, and press Enter.
2. Scroll down to find ElyseBackendReadOnly in the list.
3. Right-click ElyseBackendReadOnly and select Start.
4. Wait a few seconds. The Status column should change to Running.

Method 2 — PowerShell

Still in the same PowerShell Administrator window. Type or paste the following commands and press Enter:

Write-Host "Starting ElyseBackendReadOnly service..."
sc.exe start ElyseBackendReadOnly

# Wait for service to start
Start-Sleep -Seconds 5

# Check service status
Write-Host "Service status:"
sc.exe query ElyseBackendReadOnly

Expected output: STATE should show 4 RUNNING.

STEP 9: VERIFY DEPLOYMENT

1. Browser test. Open a web browser and navigate to http://localhost:5001/api/eula/read (adjust the port if you used a different value in SERVER_URLS). You should see JSON data displayed in the browser. If you see an error page, proceed to the log check below.
2. PowerShell test (alternative). Open PowerShell. Type or paste the following command and press Enter:

   Invoke-WebRequest -Uri "http://localhost:5001/api/eula/read" -UseBasicParsing

   Expected: StatusCode: 200 with JSON data.

3. Check the application logs. In PowerShell, type or paste the following commands and press Enter:

   Get-Content "C:\ElyseReadOnly\Backend\logs\stdout*.log" -Tail 50

   Look for “Now listening on: http://localhost:5001” and no ERROR messages.

NETWORK SECURITY

If the read-only backend will serve users from other computers (e.g. a public-facing web interface), you need to configure both the backend binding and the firewall.

Configure Network Binding

By default, the backend listens on http://localhost:5001, which only accepts connections from the local machine. To accept connections from other computers, edit the .env file and change SERVER_URLS:

After changing SERVER_URLS, restart the service (right-click ElyseBackendReadOnly in Services and select Restart).

Configure Windows Firewall

If accepting network connections, open PowerShell as Administrator and create a firewall rule:

# Allow inbound connections to the read-only backend
New-NetFirewallRule -DisplayName "Elyse Read-Only Backend" `
    -Direction Inbound -LocalPort 5001 -Protocol TCP `
    -Action Allow -Profile Domain,Private

# Verify the rule was created
Get-NetFirewallRule -DisplayName "Elyse Read-Only*" | Format-Table DisplayName, Enabled, Action

COEXISTENCE WITH OTHER BACKENDS

The read-only backend is designed to run alongside an existing SERVER or standard WORKGROUP backend on the same database. To avoid conflicts:

Both backends connect to the same database. The read-only backend only activates the READER application role, so it cannot modify any data regardless of what requests are sent to it.

UPDATING TO A NEW RELEASE

When a new version of Elyse is released, follow these steps to update the read-only backend while preserving your configuration. Two methods are provided: a manual method using File Explorer and the Services application, and a PowerShell script method.

Method 1 — Manual Update (File Explorer + Services)

1. Backup current version. Open File Explorer. Navigate to C:\ElyseReadOnly\. 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).
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.
3. Stop the service. Open the Services application (services.msc). Find ElyseBackendReadOnly in the list, right-click it, and select Stop. Wait a few seconds for the service to stop.
4. Extract the new package. Locate the new Elyse-Backend-*-WORKGROUP-READ_ONLY-*.zip file. Right-click it and select Extract All..., choose a temporary location (e.g. C:\Temp\ElyseReadOnly), and click Extract.
5. Replace the executable. In File Explorer, navigate to C:\ElyseReadOnly\Backend. Right-click the old elyse_asp-backend.exe and select Delete. Open a second File Explorer window, navigate to the extraction folder, right-click the new elyse_asp-backend.exe, select Copy, then switch to the backend directory window and press Ctrl+V to paste.
   Important: Do NOT replace the .env file — keep your existing .env with your READER password!
6. 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 READER_PASSWORD is set. Close Notepad.
7. Start the service. In the Services application, find ElyseBackendReadOnly, right-click it, and select Start. Wait a few seconds for the service to start. The Status column should change to Running.
8. Test. Open a web browser and navigate to http://localhost:5001/api/eula/read. You should see JSON data.

Method 2 — PowerShell Script

Open PowerShell as Administrator (right-click Windows PowerShell and select Run as administrator). In the script below, you must edit the $packagePath variable (marked with EDIT THIS) to match the folder where you extracted the new ZIP. Then type or paste the edited script and press Enter:

$BackendPath = "C:\ElyseReadOnly\Backend"
$BackupPath = "C:\ElyseReadOnly\Backend_Backup_$(Get-Date -Format 'yyyyMMdd_HHmmss')"
$ServiceName = "ElyseBackendReadOnly"

# Step 1: Backup current version
Write-Host "Creating backup..."
Copy-Item -Path "$BackendPath" -Destination "$BackupPath" -Recurse -Force
Write-Host "Backup created at: $BackupPath"

# Step 2: Stop the service
Stop-Service $ServiceName
Write-Host "Service stopped"

# Step 3: Replace executable
# === EDIT THIS: Set to the folder where you extracted the new ZIP ===
$packagePath = "C:\Temp\ElyseReadOnly"
Remove-Item "$BackendPath\elyse_asp-backend.exe" -Force
Copy-Item "$packagePath\elyse_asp-backend.exe" -Destination "$BackendPath\" -Force

# Step 4: Verify .env file
if (-not (Test-Path "$BackendPath\.env")) {
    Write-Host "WARNING: .env file is missing! Restoring from backup..." -ForegroundColor Yellow
    Copy-Item "$BackupPath\.env" -Destination "$BackendPath\.env" -Force
}

# Step 5: Start and verify
Start-Service $ServiceName
Start-Sleep -Seconds 5
Get-Service $ServiceName
Invoke-WebRequest -Uri "http://localhost:5001/api/eula/read" -UseBasicParsing
Write-Host "Update complete." -ForegroundColor Green

ROLLBACK PROCEDURE

If the new version has issues, restore the previous version from the backup you created during the update.

Method 1 — Manual Rollback (File Explorer + Services)

1. Stop the service. Open the Services application (services.msc). Find ElyseBackendReadOnly, right-click it, and select Stop.
2. Delete the new executable. In File Explorer, navigate to C:\ElyseReadOnly\Backend. Right-click elyse_asp-backend.exe and select Delete.
3. Restore from backup. Navigate to your backup folder (e.g. C:\ElyseReadOnly\Backend_Backup_20260415). Right-click elyse_asp-backend.exe and select Copy. Navigate back to the Backend folder and press Ctrl+V to paste.
4. Start the service. In the Services application, find ElyseBackendReadOnly, right-click it, and select Start.
5. Test. Open a web browser and navigate to http://localhost:5001/api/eula/read. You should see JSON data.

Method 2 — PowerShell Rollback

$ServiceName = "ElyseBackendReadOnly"

# Stop the service
Stop-Service $ServiceName

# Restore from backup
$BackendPath = "C:\ElyseReadOnly\Backend"
$BackupPath = "C:\ElyseReadOnly\Backend_Backup_*"
$LatestBackup = Get-ChildItem "$BackupPath" | Sort-Object LastWriteTime -Descending | Select-Object -First 1

Remove-Item "$BackendPath\elyse_asp-backend.exe" -Force
Copy-Item "$LatestBackup\elyse_asp-backend.exe" -Destination "$BackendPath\"

# Start the service
Start-Service $ServiceName

Cleanup Old Backups

After confirming the new version works, keep the 2 most recent backups and delete older ones.

In File Explorer, navigate to C:\ElyseReadOnly\. You will see folders named Backend_Backup_YYYYMMDD (or similar). Right-click any old backup folders you no longer need and select Delete.

Or via PowerShell:

$BackupPath = "C:\ElyseReadOnly\Backend_Backup_*"
Get-ChildItem "$BackupPath" | Sort-Object LastWriteTime -Descending | Select-Object -Skip 2 | Remove-Item -Recurse -Force

SERVICE MANAGEMENT

You can also manage the service via the Services GUI (run services.msc). In the Services window, scroll down to find “ElyseBackendReadOnly”. Right-click it to see options for Start, Stop, and Restart.

NEXT STEPS

1. Install a frontend instance pointing to the read-only backend: Frontend Installation. Configure the frontend’s config.json to use the read-only backend’s URL and port (e.g. http://localhost:5001/api).
2. Bootstrapping is not required for read-only deployments.