Production Deployment (IIS)

When do you need this? By default, Primentra runs directly as a Windows Service and is accessible at http://localhost:{port} (or via the server's IP on your network). IIS is optional — use it if you need:

• HTTPS/SSL termination — secure access via a certificate
• Custom domain name — access via https://primentra.yourcompany.com instead of an IP and port
• Port 80/443 — standard HTTP/HTTPS ports without specifying a port number
• Reverse proxy — layer Primentra behind an existing IIS server

How Primentra works without IIS: Primentra consists of two parts: a set of static files (the web interface — HTML, CSS, JavaScript) and an API server (a background service that talks to the database). The Windows Service runs the API server on a port you choose during installation (e.g. port 3001). When you open Primentra in your browser, the browser downloads the static files and then talks to the API on that same port.

This works fine on its own. IIS only comes into play when you want extras like HTTPS, a clean domain name, or standard ports (80/443).

What is a Single Page Application (SPA)? Primentra is a Single Page Application. That means the browser loads one HTML page (index.html) at startup, and from that point on the application handles all navigation itself — without reloading the page from the server. When you click on a model, open settings, or switch tabs, the URL in your address bar changes (e.g. /admin/models, /data/products), but the browser never actually requests those paths from the server. It all happens inside the JavaScript that was already loaded.

This creates a problem: if you refresh the page while on /admin/models, or paste that URL directly into a new browser tab, the web server receives a request for /admin/models. That path does not exist as an actual file on the server — there is no admin/models/index.html. Without special configuration, the server returns a 404 error.

The SPA fallback rule solves this. It tells the web server: "If someone requests a path that is not an actual file or folder on disk, serve index.html instead." The browser then loads the application, reads the URL, and navigates to the right page — all in JavaScript.

How the web.config works: The web.config file in the installation folder contains one rewrite rule:

<rule name="SPA Fallback" stopProcessing="true">
  <match url=".*" />                              <!-- match every URL -->
  <conditions>
    <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />       <!-- not a real file -->
    <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />  <!-- not a real folder -->
  </conditions>
  <action type="Rewrite" url="/index.html" />      <!-- serve index.html instead -->
</rule>

In plain language: "If the request is not for an existing file (like a JavaScript bundle, an image, or a font) and not for an existing folder, rewrite the request to /index.html." This is the industry-standard way to host a Single Page Application on IIS.

Architecture:

Browser  →  IIS (port 80/443)  →  Static files (dist/ folder) + SPA fallback
                                →  /api/* proxied to Primentra service (port 3001)

IIS serves two roles: it delivers the static web files from the dist/ folder (with the SPA fallback for clean URLs), and it proxies all /api/* requests to the Primentra background service which handles database operations.

Setup steps:

1. Set up IIS — Create a new website pointing to the Primentra installation folder's dist/ subfolder
2. Install URL Rewrite — Required for SPA routing. Free download from microsoft.com/iis/url-rewrite
3. Configure rewrites — The web.config file in the installation folder handles SPA routing automatically. No manual configuration needed — just make sure URL Rewrite is installed
4. Configure reverse proxy — Install Application Request Routing (ARR) and create a rule to proxy /api/* to http://localhost:{port}
5. Configure SSL — Add an SSL certificate to the IIS site for HTTPS