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 API looks for the company in this order:

1. The company whose Url is that address. Set it in the DBA Console: Companies → Edit → Url. This is the easiest way, and works for any address.
2. An address listed in LOGIN_HOST_MAP in the API's .env.
3. The first part of the host name, matched to the company code without regard to case.

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).

Then click Edit on each company and enter its address in Url, e.g. acme.demo.ritzy.net.au (with or without https://). The Companies list shows each Url. Two companies cannot share one. If you leave Url empty, the company's code is used as its 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. Give the phone apps their path addresses: https://acme.ritzy.net.au/track/, /statement/, /crm/ and so on (the list is in the Mobile Apps manual, section 1). Nothing else is needed: the paths are on port 443 with the web app and covered by the same certificate. Set them in Tools → PWA Apps so the QR codes point there.
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, which also serves every phone app under its path:

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 are under paths on the same address, e.g. acme.demo.ritzy.net.au/track/. CORS_ORIGIN does not need changing: each page talks to the API through its own address, and the paths are the same origin as the web app.

Optional: send unknown addresses to your website

With a wildcard record, any name reaches the server, so anything.ritzy.net shows an empty sign-in page. To send such addresses to your website instead, add this to the port 80 server { } block, above location /, and the two lines marked inside location /:

# An address that names no company goes to the website. The API answers 204 or 403.
location = /_host_check {
    internal;
    proxy_pass http://127.0.0.1:3001/api/auth/host-check;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header Host $host;
}
location @unknown_host {
    return 302 https://ritzy.net.au/;
}

location / {
    root C:/RitzyOne/packages/web/dist;
    auth_request /_host_check;          # add
    error_page 403 = @unknown_host;     # add
    ...
}

It needs a Ritzy One API from November 2026 or later (which has /api/auth/host-check). With LOGIN_COMPANY_SCOPE off every address passes, so it is harmless there. The phone apps' location /track/ … blocks in the same server can take the same two lines. Every page request asks the API first, so if the API is stopped the pages show 500 instead of loading.

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. If you added the optional redirect in step 3, an address that names no company opens your website instead of the sign-in page.
3. Open http://psk.demo.ritzy.net.au. It shows only PSK.
4. Open an address that names no company, e.g. http://www.demo.ritzy.net.au. The company list is empty.
5. Open /api/auth/companies on each address, e.g. http://acme.demo.ritzy.net.au/api/auth/companies. It returns one company, or [].
6. Check a phone app too, e.g. http://acme.demo.ritzy.net.au/track/.
7. 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.