Companies on Their Own Subdomains

1 What it does

A Ritzy One install keeps all its companies in one PostgreSQL database. Row-Level Security already keeps each company's data apart. But by default the sign-in page lists every company on the install to anyone who opens it, so two prospects sharing a demo server would see each other's company names.

With LOGIN_COMPANY_SCOPE=host the address in the browser decides the company:

• The sign-in page lists only that address's company, and selects it automatically.
• Signing in to any other company from that address fails with Invalid user ID or password, the same message as a wrong password, so it never reveals which other companies exist.
• An address that names no company lists nothing and signs nobody in.

It applies to the web app and all the phone apps (they share the same sign-in), the tenant portal's contract-number sign-in, and the public /api/auth/diag connection check. Tenant portal invitation links are not affected: the link itself names the account.

2 How an address picks its company

The company is the first part of the host name, matched to the company code without regard to case. LOGIN_HOST_MAP overrides that for any address you list.

3 When to use it, and when not

4 Step 1 — Add the companies

In the DBA Console, add each company to the install:

• New Company for a fresh or sample company, or
• Import from Firebird to bring a company across from Ritzy 8 (its DB_<code>.FDB).

Write down each company's code. It becomes that company's subdomain:

Give each prospect their own user in their own company. Do not give them DBA rights (see section 11).

5 Step 2 — Point the names at the server

On the internet

At your DNS provider, add one wildcard record. It covers every company, now and later, with no further DNS work:

*.demo.ritzy.net.au   A   <the server's public IP>

If the domain is on Cloudflare, follow section 5a instead: there's a choice to make there that affects the phone apps and HTTPS.

On your own network, for testing

No DNS is needed. On each PC you test from, open Notepad as Administrator, edit C:\Windows\System32\drivers\etc\hosts and add a line per company:

192.168.1.214   psk.ritzy.lan
192.168.1.214   acme.ritzy.lan

Use the server's own address in place of 192.168.1.214.

5a If the domain's DNS is on Cloudflare

In the Cloudflare dashboard, open the domain (ritzy.net.au) and go to DNS → Records. First decide how the subdomains go through Cloudflare. That is the Proxy status switch on the record:

Option A — DNS only

1. Add record: Type A, Name *.demo, IPv4 address = the server's public IP, Proxy status DNS only (grey cloud), TTL Auto. Save.
2. That's all on the Cloudflare side. Do the certificate on the server (step 5). Caddy's automatic certificates work because visitors, and the certificate check, reach the server directly on port 80.
3. Test from any PC: nslookup acme.demo.ritzy.net.au answers with the server's IP.

Option B — Proxied

1. Add record: Type A, Name * for acme.ritzy.net.au-style names (or *.demo if you have Advanced Certificate Manager), IPv4 address = the server's public IP, Proxy status Proxied (orange cloud). Records you already have (www, docs, lic2…) keep working: a named record always wins over the wildcard.
2. SSL/TLS → Overview: set encryption mode to Full (strict). Never Flexible: that sends passwords unencrypted between Cloudflare and the server.
3. SSL/TLS → Origin Server → Create Certificate: keep the hostnames *.ritzy.net.au and ritzy.net.au (add *.demo.ritzy.net.au if you use that), 15 years. Save the certificate and private key as two files on the server, e.g. C:\nginx\conf\ssl\ritzy-origin.pem and ritzy-origin.key, and point nginx at them:

   listen 443 ssl;
   ssl_certificate     C:/nginx/conf/ssl/ritzy-origin.pem;
   ssl_certificate_key C:/nginx/conf/ssl/ritzy-origin.key;

   This certificate is only trusted by Cloudflare, which is all it needs to be: visitors see Cloudflare's certificate.
4. SSL/TLS → Edge Certificates: turn on Always Use HTTPS.
5. Caching → Cache Rules: add a rule URI Path starts with /api/ → Bypass cache, so no API answer is ever served from Cloudflare's cache.
6. Move the phone apps to Cloudflare-supported HTTPS ports (2053, 2083, 2087, 2096, 8443), or don't use them through this address.
7. Optional but worthwhile: on the server's firewall, allow ports 80/443 only from Cloudflare's IP ranges, so nobody can reach the server around Cloudflare.

6 Step 3 — nginx

nginx must hand the address the visitor typed to the API. The standard Ritzy One config already does this in every location /api/ block. Check it is there:

location /api/ {
    proxy_pass http://127.0.0.1:3001;
    proxy_set_header Host $host;   # required: the API reads the company from this
    ...
}

Then add the subdomains to the server_name line of each server { } block in C:\nginx\conf\nginx.conf, the web app on port 80 and each phone app on its own port:

server_name 192.168.1.214 *.demo.ritzy.net.au *.ritzy.lan;

Take a copy of nginx.conf first. Then test the config and restart nginx in PowerShell, as Administrator:

cd C:\nginx
.\nginx.exe -t
Restart-Service nginx

The phone apps keep their ports, e.g. acme.demo.ritzy.net.au:8081. CORS_ORIGIN does not need changing: each page talks to the API through its own address.

7 Step 4 — Turn it on

The setting goes in the API's settings file, C:\RitzyOne\packages\api\.env, not a .env in the install folder's root. On installs from November 2026 there is a commented-out section for it at the end of the file.

LOGIN_COMPANY_SCOPE=host
# Any address that is not a company code, comma-separated (address=CODE):
LOGIN_HOST_MAP=192.168.1.214=PSK,localhost=PSK,demo2.demo.ritzy.net.au=DEMO_2

Then restart the API in PowerShell, as Administrator:

Restart-Service ritzy-api

8 Step 5 — HTTPS

Before prospects sign in over the internet, put the addresses on HTTPS. Passwords should not travel in plain text, and the phone apps can only be installed from an HTTPS address.

• Docker host: the ready-made docker/trial-proxy (Caddy) gets and renews a certificate for each subdomain by itself. It needs ports 80 and 443 free and the wildcard DNS record from step 2.
• Behind Cloudflare's proxy (orange cloud): Cloudflare handles visitors' HTTPS; install a Cloudflare Origin Certificate on the server as described in section 5a, option B.
• Windows server with nginx: use a certificate tool such as win-acme to get a wildcard certificate for *.demo.ritzy.net.au (a wildcard needs DNS validation at your DNS provider), then add listen 443 ssl; with the certificate files to each server block.

9 Check that it works

1. Open http://acme.demo.ritzy.net.au. The company box shows only ACME, already selected. Sign in.
2. Open http://psk.demo.ritzy.net.au. It shows only PSK.
3. Open an address that names no company, e.g. http://www.demo.ritzy.net.au. The company list is empty.
4. Open /api/auth/companies on each address, e.g. http://acme.demo.ritzy.net.au/api/auth/companies. It returns one company, or [].
5. Check a phone app too, e.g. http://acme.demo.ritzy.net.au:8081.
6. If staff use the IP address, check it still signs in to the company you mapped.

10 On a Docker stack

A Docker stack reads its settings from the stack's .env (beside its docker-compose.yml). Add the same two lines there and restart the stack:

LOGIN_COMPANY_SCOPE=host
LOGIN_HOST_MAP=demo2.demo.ritzy.net.au=DEMO_2

docker compose up -d

Caddy in docker/trial-proxy passes the address on by default. Point every prospect's subdomain at the one shared demo stack's port.

11 What it does not cover

• The DBA Console. A DBA user of any company can still see every company on the install there. Never give a prospect DBA rights on a shared install.
• Data separation is not changed by this setting: Row-Level Security already does that. This setting hides the names on the sign-in pages.
• Backups, upgrades and downtime are shared by every company on the install. A customer who needs their own schedule needs their own stack.
• Company Setup on the sign-in page (DBA, support password) lists only the companies visible at that address. Use the DBA Console for the full list.

12 Troubleshooting

13 Turning it off

Put a # back in front of LOGIN_COMPANY_SCOPE=host (or set it to all) and run Restart-Service ritzy-api. Every address lists every company again. Nothing is stored in the database, so turning it on and off is safe at any time.