Installation Options

RegScale supports several deployment models so you can match your security, scale, and operational requirements. Review the options below, then follow the guide for your chosen model.

📘

Before you install

Complete the Prerequisites and review the Sizing Guide first. After installation, follow the Post-Deployment Steps.

Deployment Options

HTTPS and Reverse Proxies

Interactive sign-in needs HTTPS. The browser session cookie is Secure, and the antiforgery
token that is issued with it can only be issued on an HTTPS request. RegScale refuses a sign-in request that arrives over plain HTTP. The response is 400 with the body HTTPS is required to sign in. Serve RegScale over HTTPS, or forward X-Forwarded-Proto from your TLS-terminating proxy. No credential is checked on a refused request.

This applies to every path that issues a session: local login, LDAP login, SAML and OIDC login, the GraphQL login mutation, change-password, token refresh, and app-context switch.

If a proxy terminates TLS in front of RegScale, the proxy must forward the original scheme:

proxy_set_header X-Forwarded-Proto $scheme;

RegScale reads X-Forwarded-Proto, X-Forwarded-For, and X-Forwarded-Host from the proxies that ForwardedHeaders:KnownProxies and ForwardedHeaders:KnownIPNetworks name. If the proxy is not in that list, the header is ignored and the request still counts as plain HTTP.

If no proxy and no CA-issued certificate are available, see HTTPS with a Self-Signed Certificate.

HTTPS with a Self-Signed Certificate

Use this configuration when no TLS-terminating proxy and no certificate from a certificate authority (CA) are available. Examples are an evaluation install or an isolated network. RegScale then terminates TLS itself, in its Kestrel web server.

A self-signed certificate encrypts the connection, but no client trusts it by default. Each browser shows a warning until the certificate is trusted on that client. For production, a certificate from your CA is better, because clients trust it with no extra step.

1. Create the certificate

Use OpenSSL 1.1.1 or later. Replace regscale.example.internal and 10.0.0.10 with each host name and IP address that users type to reach RegScale. Browsers reject a certificate that does not list the host name in subjectAltName.

openssl req -x509 -newkey rsa:3072 -sha256 -days 365 -nodes \
  -keyout regscale.key -out regscale.crt \
  -subj "/CN=regscale.example.internal" \
  -addext "subjectAltName=DNS:regscale.example.internal,IP:10.0.0.10" \
  -addext "extendedKeyUsage=serverAuth"

Kestrel reads the certificate and its key from one PFX file. Put the PFX password in REGSCALE_CERT_PASSWORD from your secret store before you run this command. Do not type the password on the command line.

openssl pkcs12 -export -out regscale.pfx \
  -inkey regscale.key -in regscale.crt \
  -passout env:REGSCALE_CERT_PASSWORD

Keep regscale.key and regscale.pfx private. Anyone who has the key can impersonate the server.

2. Configure the container

Mount the PFX file read-only. Then tell Kestrel to listen on HTTPS and to use the certificate:

services:
  backend:
    environment:
      ASPNETCORE_URLS: "https://+:443;http://+:80"
      ASPNETCORE_Kestrel__Certificates__Default__Path: /https/regscale.pfx
      ASPNETCORE_Kestrel__Certificates__Default__Password: ${REGSCALE_CERT_PASSWORD}
    ports:
      - "443:443"
      - "80:80"
    volumes:
      - ./certs/regscale.pfx:/https/regscale.pfx:ro

Keep the HTTP port open. RegScale redirects a plain-HTTP request to HTTPS, so users who type http:// arrive at the HTTPS address.

If you publish HTTPS on a host port other than 443, set ASPNETCORE_HTTPS_PORT to that host port. Otherwise, the redirect sends users to port 443.

3. Restart and test

Restart the container. Then send a request that trusts the new certificate:

curl --cacert regscale.crt https://regscale.example.internal/health

If curl reports a certificate error, make sure that the host name in the URL is in the subjectAltName of the certificate.

4. Trust the certificate on each client

Install regscale.crt (not the PFX file, which contains the private key) as a trusted root on each client:

5. Replace the certificate before it expires

The command in step 1 makes a certificate that is valid for 365 days. Before that date, create a new certificate and trust it on each client. Then replace the PFX file and restart the container.

CAUTION: Trust the new certificate on the clients before you replace the old one. RegScale sends an HSTS header, which ASP.NET Core sets to 30 days by default. For that period, a browser does not let a user continue past a certificate error for the RegScale host name.

Supported Platforms

Operating Systems

• Preferred: Ubuntu, Red Hat Enterprise Linux (RHEL)
• Supported for local testing: Windows 10/11 (with WSL), macOS

Browsers

• ✅ Fully supported: Google Chrome, Microsoft Edge
• ⚠️ Best-effort: Safari, Firefox
• ❌ Not supported: Internet Explorer

Screen Resolution

• Minimum recommended: 1920 x 1080
• Mobile not officially supported; tablet experience optimized (iPad, Surface)

Development Environments

You may run a DEV instance of RegScale at no additional cost.

Recommendations:

• Mirror your production setup (same deployment model).
• Test upgrades and features safely before applying them to production.
• Back up your database and file storage before applying changes.