Production Deployment (IIS)

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.

Model A — reverse proxy with ARR (recommended)

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.
6. For HTTPS, add an https binding on 443 with a certificate your clients trust.

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: icacls "<install folder>" /grant "IIS AppPool\<pool-name>:(OI)(CI)M" /T

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.

Troubleshooting

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

Related

• Manual Installation (ZIP) — register the service by hand
• Health & Monitoring — check the API through the proxy
• Database Connection — connection settings and the test button
• Troubleshooting — service and database errors