Backend Installation (Workgroup / Single-User)

OVERVIEW

This page covers the installation of the Elyse .NET backend for WORKGROUP deployments — a single user on a Windows 10/11 workstation, not joined to a domain.

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 the user’s own account.

• For server (multi-user, domain/KCD) deployments, see Backend Installation (Server).
• For the frontend installation, see Frontend Installation.

SINGLE-USER DEPLOYMENT ONLY

This WORKGROUP deployment is designed for one user on one machine.

PREREQUISITES

• Windows 10/11 (any edition)
• SQL Server (Express or higher) installed and configured per SQL Server & Database
• Database restored per SQL Server & Database
• Administrative access to PowerShell (for service creation)
• The 6 application role passwords from your DBA

PACKAGE CONTENTS

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

PREREQUISITE: SQL SERVER LOGIN

Before deploying the backend, a SQL Server login must be created for the Windows account that will run the service. This step replaces the AD group login used in SERVER deployments.

Create the SQL Server Login

Open SQL Server Management Studio (SSMS). In the “Connect to Server” dialog, set Server name to .\ (for Default Instance) or .\SQLEXPRESS (for Named Instance), set Authentication to Windows Authentication, and click Connect.

Click the New Query button in the toolbar (or press Ctrl+N). In the script below, replace COMPUTERNAME\Username with the actual computer name and username (e.g. DESKTOP-ABC123\JohnDoe) before executing. Then press F5 to execute:

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

Alternatively, use the 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 local computer name (not a domain). Click OK.
5. Click Advanced..., then click Find Now. A list of local users will appear.
6. Select your user account from the list and click OK.
7. Click OK again. The login name should now show as COMPUTERNAME\Username.
8. Click OK to create the login.

Grant Database Access

The user only needs CONNECT permission. All actual data permissions come from application roles.

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 your account name (e.g. DESKTOP-ABC123\JohnDoe). 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, in SSMS 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\Username with the actual computer name and username (e.g. DESKTOP-ABC123\JohnDoe) before executing. Then press F5 to execute:

USE [Elyse_DB];
GO
CREATE USER [COMPUTERNAME\Username] FOR LOGIN [COMPUTERNAME\Username];
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. In the address bar, type %LOCALAPPDATA% and press Enter. This navigates to your local application data folder (e.g. C:\Users\JohnDoe\AppData\Local).
2. Right-click in the empty space and select New > Folder. Name the folder ElyseApp and press Enter.
3. Double-click the ElyseApp 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: %LOCALAPPDATA%\ElyseApp\Backend\logs (e.g. C:\Users\JohnDoe\AppData\Local\ElyseApp\Backend\logs).

Method 2 — PowerShell

Alternatively, open PowerShell as the regular user (do not right-click and “Run as administrator” — just open it normally). Type or paste the following commands and press Enter:

$BackendPath = "$env:LOCALAPPDATA\ElyseApp\Backend"
Write-Host "Creating backend directory for user: $env:USERNAME"
Write-Host "Directory: $BackendPath"
New-Item -ItemType Directory -Path "$BackendPath" -Force
New-Item -ItemType Directory -Path "$BackendPath\logs" -Force

Expected output: Directory paths showing successful creation (e.g. C:\Users\JohnDoe\AppData\Local\ElyseApp\Backend).

STEP 2: DEPLOY FILES

1. Locate the workgroup backend deployment package file (Elyse-Backend-*-WORKGROUP-*.zip) that you downloaded.
2. Right-click the zip file and select Extract All...
3. Choose a temporary extraction location (e.g., C:\Temp\ElyseWorkgroup) and click Extract.
4. Open File Explorer. In the address bar, type %LOCALAPPDATA%\ElyseApp\Backend and press Enter. This navigates to the backend directory created in Step 1 (e.g., C:\Users\YourUsername\AppData\Local\ElyseApp\Backend).
   Tip: %LOCALAPPDATA% is a Windows shortcut that expands to C:\Users\YourUsername\AppData\Local. You can type it directly in the File Explorer address bar.
5. Open a second File Explorer window and navigate to the temporary extraction folder (e.g., C:\Temp\ElyseWorkgroup).
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 %LOCALAPPDATA%\ElyseApp\Backend\ (type this path in the address bar and press Enter).
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. localhost\SQLEXPRESS or 192.168.1.50
   DB_NAME	Elyse_DB	Default database name
   USE_KCD	false	Required — do not change for WORKGROUP
   SERVER_URLS	http://localhost:5000	Most secure option (localhost only)

6. Set all 6 application role passwords (get these from your DBA):

   CONFIGURATOR_PASSWORD=actual_password_here
   READER_PASSWORD=actual_password_here
   REVIEWER_PASSWORD=actual_password_here
   CONTROLLER_PASSWORD=actual_password_here
   EDITOR_PASSWORD=actual_password_here
   AUTHORISER_PASSWORD=actual_password_here

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

Open PowerShell as the regular user (do not run as Administrator):

Type or paste the following commands and press Enter:

$BackendPath = "$env:LOCALAPPDATA\ElyseApp\Backend"
$CurrentUser = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name
Write-Host "Securing .env file for user: $CurrentUser"

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

# Grant access only to current user and SYSTEM
icacls "$BackendPath\.env" /grant "NT AUTHORITY\SYSTEM:(M)"
icacls "$BackendPath\.env" /grant "${CurrentUser}:(M)"

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

STEP 5: SET FOLDER PERMISSIONS

Still in the same PowerShell window (as regular user). Type or paste the following commands and press Enter:

$BackendPath = "$env:LOCALAPPDATA\ElyseApp\Backend"
$CurrentUser = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name
Write-Host "Setting folder permissions for user: $CurrentUser"

# Grant current user read/execute access to backend folder
icacls "$BackendPath" /grant "${CurrentUser}`:(OI)(CI)RX" /T

# Grant current user write access to logs folder
icacls "$BackendPath\logs" /grant "${CurrentUser}`:(OI)(CI)M" /T

Write-Host "Permissions set successfully"

STEP 6: GRANT LOG ON AS A SERVICE

Your Windows account needs the “Log on as a service” permission before it can run a Windows Service. An administrator must grant this.

Open the Local Security Policy editor (run secpol.msc as Administrator — right-click and select Run as administrator). This step must be performed by an administrator account.

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 your user account (the regular Windows account, e.g. JohnDoe) 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 ElyseBackend
sc.exe delete ElyseBackend

The script below automatically detects your computer name, username, and backend path. It will prompt you for your Windows password (the input is masked for security). No manual editing is required.

# Auto-detect all values
$BackendPath = "$env:LOCALAPPDATA\ElyseApp\Backend"
$ServiceName = "ElyseBackend"
$ExePath = "$BackendPath\elyse_asp-backend.exe"
$ServiceUser = "$env:COMPUTERNAME\$env:USERNAME"

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

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

# Prompt for Windows password (masked input)
$SecurePassword = Read-Host "Enter your Windows password" -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 user 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 - 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 ElyseBackend in the list.
3. Right-click ElyseBackend 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 ElyseBackend service..."
sc.exe start ElyseBackend

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

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

Expected output: STATE should show 4 RUNNING.

STEP 9: VERIFY DEPLOYMENT

1. Browser test. Open a web browser and navigate to http://localhost:5000/api/eula/read. 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 a new PowerShell window as the regular user (do not run as Administrator). Type or paste the following command and press Enter:

   Invoke-WebRequest -Uri "http://localhost:5000/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:

   $BackendPath = "$env:LOCALAPPDATA\ElyseApp\Backend"
   Get-Content "$BackendPath\logs\stdout*.log" -Tail 50

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

NETWORK SECURITY (OPTIONAL)

Recommended: Localhost-Only Binding (Default)

The default configuration uses localhost binding (SERVER_URLS=http://localhost:5000). This makes it impossible for other computers to connect, even if the firewall is off. This is the most secure option.

Alternative: Allow Network Access

If you need to allow other computers to access your backend (not recommended for workgroup), open PowerShell as Administrator (right-click Windows PowerShell and select Run as administrator):

# Block all external access by default
New-NetFirewallRule -DisplayName "Elyse Backend - Block All" `
    -Direction Inbound -LocalPort 5000 -Protocol TCP `
    -Action Block -Profile Domain,Private,Public

# Allow access only from specific trusted computers
New-NetFirewallRule -DisplayName "Elyse Backend - Allow Frontend" `
    -Direction Inbound -LocalPort 5000 -Protocol TCP `
    -Action Allow -RemoteAddress "192.168.1.100" `
    -Profile Domain,Private

# Verify firewall rules
Get-NetFirewallRule -DisplayName "Elyse Backend*" | Format-Table DisplayName, Enabled, Action

Replace 192.168.1.100 with the actual IP address of the computer that needs access.

UPDATING TO A NEW RELEASE

When a new version of Elyse is released, follow these steps to update the WORKGROUP 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. In the address bar, type %LOCALAPPDATA%\ElyseApp\ and press Enter. 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. Stop the service. Open the Services application (press the Windows key, type services.msc, press Enter). Find ElyseBackend 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-*.zip file. Right-click it and select Extract All..., choose a temporary location (e.g. C:\Temp\ElyseUpdate), and click Extract.
5. Replace the executable. In File Explorer, navigate to %LOCALAPPDATA%\ElyseApp\Backend (type this in the address bar and press Enter). Right-click the old elyse_asp-backend.exe and select Delete. Open a second File Explorer window, navigate to the extraction folder (e.g. C:\Temp\ElyseUpdate), 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 passwords!
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 the application role passwords are present. Close Notepad.
7. Start the service. In the Services application (still open from step 3), find ElyseBackend, 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:5000/api/eula/read. You should see JSON data. If you see an error, check the logs in %LOCALAPPDATA%\ElyseApp\Backend\logs\.

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 = "$env:LOCALAPPDATA\ElyseApp\Backend"
$BackupPath = "$env:LOCALAPPDATA\ElyseApp\Backend_Backup_$(Get-Date -Format 'yyyyMMdd_HHmmss')"

# 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 ElyseBackend
Write-Host "Service stopped"

# Step 3: Replace executable
# === EDIT THIS: Set to the folder where you extracted the new ZIP ===
$packagePath = "C:\Temp\ElyseUpdate"
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 ElyseBackend
Start-Sleep -Seconds 5
Get-Service ElyseBackend
Invoke-WebRequest -Uri "http://localhost:5000/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 ElyseBackend, right-click it, and select Stop.
2. Delete the new executable. In File Explorer, navigate to %LOCALAPPDATA%\ElyseApp\Backend. Right-click elyse_asp-backend.exe and select Delete.
3. Restore from backup. Navigate to your backup folder (e.g. %LOCALAPPDATA%\ElyseApp\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 ElyseBackend, right-click it, and select Start.
5. Test. Open a web browser and navigate to http://localhost:5000/api/eula/read. You should see JSON data.

Method 2 — PowerShell Rollback

# Stop the service
Stop-Service ElyseBackend

# Restore from backup
$BackendPath = "$env:LOCALAPPDATA\ElyseApp\Backend"
$BackupPath = "$env:LOCALAPPDATA\ElyseApp\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 ElyseBackend

Cleanup Old Backups

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

In File Explorer, navigate to %LOCALAPPDATA%\ElyseApp\. 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 = "$env:LOCALAPPDATA\ElyseApp\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 “ElyseBackend”. Right-click it to see options for Start, Stop, and Restart.

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.

For WORKGROUP deployments, the username should match the Windows account that the backend service is running under (the account configured in Step 7). This is typically the user’s own account (e.g. COMPUTERNAME\JohnDoe).

WORKGROUP READ ONLY VARIANT

The WORKGROUP READ ONLY backend is a separate 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 and is typically deployed alongside an existing SERVER backend in a domain environment.

Because the read-only variant has significantly different deployment requirements (dedicated service account, different .env configuration, different permissions, no bootstrapping), it has its own dedicated installation guide:

→ Backend Installation (Read-Only)

NEXT STEPS

1. Install the frontend application layer: Frontend Installation
2. After both layers are installed, proceed to Bootstrapping and Configuration to onboard the user and assign all roles (follow the single-user path).