Documentation
Use Primentra
Getting Started
Data Grid
Approvals
Set up
Modeling
Business Rules
Users & Roles
Sign-in & Security
Install and run
Installation
Administration
Integration & API
Architecture
Migrate from MDS
Migrating from MDS
Documentation/Installation/Production Deployment (IIS)

Production Deployment (IIS)

On this page
IIS Request Flow

Select a scenario to see how IIS handles different types of requests. The animated dot shows the request traveling through each component.

Browser requests /admin/models — a page that doesn't exist as a file
Browser
Your laptop
IIS
Port 80 / 443
URL Rewrite
web.config rule
ARR Proxy
Reverse proxy module
Primentra API
localhost:3001
SQL Server
Stored procedures
GET /admin/models
Step 1/5

Primentra runs as a Windows service and answers on http://localhost:{port} without any web server in front of it. IIS is optional.

When you need IIS

  • HTTPS — TLS termination with a certificate.
  • A custom domain — https://primentra.yourcompany.com instead of an IP and port.
  • Port 80 or 443 — no port number in the URL.
  • Reverse proxy — Primentra behind an IIS server you already run.

How Primentra works without IIS

Primentra has two parts: static files, which are the web interface, and an API server that talks to the database. The Windows service runs both on the port you chose during installation. The browser downloads the static files and then calls the API on that same port.

The SPA fallback rule

Primentra is a single page application. The browser loads index.html once, and the application handles navigation itself. The address bar changes to paths such as /admin/models, but the browser never requests those paths from the server.

That breaks on a refresh. Reload while on /admin/models and the web server receives a request for a path that is not a file on disk, so it returns 404.

The SPA fallback rule fixes it. It tells the web server to serve index.html for any path that is not a real file or folder. The application then reads the URL and navigates itself.

IIS serves the static files and forwards /api to the Windows service.

Browser  →  IIS (port 80/443)  →  Static files (dist/ folder) + SPA fallback
                               →  /api/* proxied to Primentra service (port 3001)
  1. Leave the Windows service running.
  2. Install the URL Rewrite and Application Request Routing (ARR) modules. Both are free from Microsoft.
  3. Enable the proxy once at server level: "%windir%\system32\inetsrv\appcmd.exe" set config -section:system.webServer/proxy /enabled:"True" /commit:apphost
  4. Create an IIS site whose physical path is the dist subfolder, bound to port 80 or 443.
  5. Set appBaseUrl in mds-config.json to the HTTPS URL users type, then restart the service. Sign-in fails without it. Only an administrator can open this file, because it holds passwords. Open Notepad with Run as administrator, see Open mds-config.json.
  6. For HTTPS, add an https binding on 443 with a certificate your clients trust.

Set up Model A with PowerShell

The same steps as commands. Run each block in PowerShell as Administrator. The example uses the default install folder and port 8080, so the Default Web Site keeps port 80.

Install IIS:

Install-WindowsFeature Web-Server -IncludeManagementTools | Select-Object Success, RestartNeeded

Install URL Rewrite and ARR from Microsoft:

Invoke-WebRequest https://download.microsoft.com/download/1/2/8/128E2E22-C1B9-44A4-BE2A-5859ED1D4592/rewrite_amd64_en-US.msi -OutFile "$env:TEMP\rewrite.msi" -UseBasicParsing; Start-Process msiexec.exe -ArgumentList '/i', "$env:TEMP\rewrite.msi", '/qn' -Wait
Invoke-WebRequest https://download.microsoft.com/download/E/9/8/E9849D6A-020E-47E4-9FD0-A023E99B54EB/requestRouter_amd64.msi -OutFile "$env:TEMP\arr.msi" -UseBasicParsing; Start-Process msiexec.exe -ArgumentList '/i', "$env:TEMP\arr.msi", '/qn' -Wait

Switch the ARR proxy on, once per server:

& "$env:windir\system32\inetsrv\appcmd.exe" set config -section:system.webServer/proxy /enabled:"True" /commit:apphost

Create the site on the dist folder. Its web.config already holds both rules:

Import-Module WebAdministration; New-Website -Name Primentra -Port 8080 -PhysicalPath "C:\Program Files\Primentra\dist" | Select-Object Name, State

Set appBaseUrl to the address users type. Use the https:// address once the site has its https binding. The command fills the empty appBaseUrl line that mds-config.json already has, and keeps the file's permissions:

$p = "C:\Program Files\Primentra\mds-config.json"; $t = [IO.File]::ReadAllText($p); [IO.File]::WriteAllText($p, $t.Replace('"appBaseUrl": ""', '"appBaseUrl": "http://localhost:8080"')); Select-String -Path $p -Pattern appBaseUrl; Restart-Service Primentra

The output must show your address. If it still shows the old value, appBaseUrl was not empty: change that line by hand. Never add a second appBaseUrl line, because the last one in the file wins.

Check that the API answers through IIS:

Start-Sleep 15; Invoke-RestMethod http://localhost:8080/api/health | Select-Object status, appVersion

Then open the address in a browser and sign in.

The web.config rules

The web.config that ships in dist does two things — proxy the API, then fall back to the SPA:

<rules>
  <!-- 1. Proxy /api to the Primentra service. MUST come before the SPA fallback. -->
  <rule name="Proxy API to Primentra service" stopProcessing="true">
    <match url="^api/(.*)" />
    <action type="Rewrite" url="http://localhost:3001/api/{R:1}" appendQueryString="true" />
  </rule>
  <!-- 2. SPA fallback: anything that is not a real file or folder serves index.html. -->
  <rule name="SPA Fallback" stopProcessing="true">
    <match url=".*" />
    <conditions logicalGrouping="MatchAll">
      <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
      <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
    </conditions>
    <action type="Rewrite" url="/index.html" />
  </rule>
</rules>

The proxy rule must come first. Otherwise /api requests are rewritten to index.html and the application receives HTML where it expects JSON. Update the port in the proxy rule if you did not install on 3001.

Model B — iisnode

IIS hosts the Node process itself. There is no separate service and no second port.

  1. Install the iisnode module and stop the Windows service.
  2. Unlock the handlers section once, at server level: "%windir%\system32\inetsrv\appcmd.exe" unlock config -section:system.webServer/handlers
  3. Create an IIS site whose physical path is the install root, not dist, and set the application pool to "No Managed Code". The web.config in the install root routes everything through iisnode.
  4. Grant the application pool write access to the install folder before the first start: icacls "<install folder>" /grant "IIS AppPool\<pool-name>:(OI)(CI)M" /T
At each start Primentra takes away the read access that ordinary Windows users have on mds-config.json and mds-config.json.bak, because the files hold passwords and the license key. An account with its own grant on a file keeps it. A folder grant made after that no longer reaches the two files. If you add the pool later, grant it on each file: icacls "<install folder>\mds-config.json" /grant "IIS AppPool\<pool-name>:M", and the same for mds-config.json.bak.
Under iisnode the per-client rate limits, such as login brute-force protection, may not see the real client IP. Use Model A for internet-facing deployments.

Prerequisites

  • Both models: IIS with the Web Server role, the URL Rewrite module, SQL Server reachable over TCP/IP, and Node.js LTS.
  • Model A also needs Application Request Routing.
  • Model B also needs the iisnode module.

SQL Server over TCP

Node connects over TCP. Enable TCP/IP for your instance and give it a fixed port in SQL Server Configuration Manager, under Protocols › TCP/IP. A named instance also needs the SQL Server Browser service.

Sign-in behind a proxy

Behind a reverse proxy the application must know the address browsers use. Set appBaseUrl in mds-config.json to your HTTPS URL, for example https://primentra.hospital.example, and restart the service. Without it, sign-in returns HTTP 500 with a CORS error. Naming the URL is also a deliberate safeguard against DNS rebinding.

Only an administrator can open mds-config.json, because it holds passwords. Open Notepad with Run as administrator, see Open mds-config.json.

Primentra does not use WebSockets. One /api proxy rule is all you need. IIS is a front door, not a replacement for the service.

Active Directory sign-in behind IIS

Behind IIS, Primentra counts a request as HTTPS only when IIS proves it.

  • With ARR (Model A), ARR adds the header X-ARR-SSL to an HTTPS request.
  • With iisnode (Model B), iisnode passes the HTTPS server variable. The web.config that ships with Primentra sets this.

Bind the site to HTTPS only. If the site also has an HTTP binding, the Windows password form stays hidden on HTTP, and Primentra refuses AD passwords there.

Two more rules:

  • appBaseUrl in mds-config.json must be the https:// address that users open.
  • Primentra believes these headers only from IIS on the same server. A proxy on another server does not count as proof of HTTPS.

See Active Directory Setup for the rest of the set-up.

Troubleshooting

SymptomCause and fix
Sign-in returns HTTP 500 or a CORS error (Model A)appBaseUrl is not set. Set it in mds-config.json and restart the service
/api returns HTML instead of JSONThe SPA fallback runs before the /api rule, or the ARR proxy is off. Put the /api rule first and enable the proxy
Blank HTTP 500 and no iisnode-logs folder (Model B)iisnode cannot find node.exe. Update nodeProcessCommandLine in web.config, or restart IIS if Node was installed after it
HTTP 500.19 (Model B)The handlers section is locked. Run the handlers unlock
EPERM on mds-config.json (Model B)The application pool has no write access. Apply the icacls grant. If Primentra has started before, grant the pool on mds-config.json and mds-config.json.bak themselves
404 on refresh or on a deep linkThe URL Rewrite module is not installed
Cannot connect to SQL ServerTCP/IP is off, or SQL Server Browser is not running for a named instance
Certificate warning in the browserThe certificate is not trusted by clients. Use one from your internal certificate authority
The Windows account choice is missing on the sign-in screen, or a Windows password is refusedThe request did not arrive over HTTPS as far as Primentra can prove. Open the https address, bind the site to HTTPS only, and set appBaseUrl to that address

The same steps ship as INSTALL.txt inside the download, for offline installs.