New Server Installation & Licensing

1Before you start

Gather these before touching the server. Stopping half-way to hunt for one of them is the usual cause of a long install.

What you need to hand

2Choose the topology

The License Server is vendor infrastructure. It holds the RSA private signing key and must never be installed on a customer's box.

3Part A — The Ritzy License Server once, ever

Skip this entire section if your License Server is already running — you only build it once and then share it across all customers. Jump to §4.

3.1 Install

1. Copy RitzyLicence-deploy.zip to the vendor server and unzip it to a permanent folder, e.g. C:\RitzyLicence. Do not run it from a temp folder — the licence database, its backups and the keys are created in data\ beside it. The licence database is Firebird: install the Firebird server (3, 4 or 5) on this machine first.
2. Open a Command Prompt as Administrator in that folder and run:

   install.cmd

3. Answer the prompts:

   Prompt	Default	What to enter
   HTTP port	4100	Keep 4100 unless it clashes. Must match your reverse proxy.
   Bootstrap admin username	admin	Your vendor console login.
   Password / Confirm password	—	A strong password. It is hashed on first boot; never leave it as changeme.
   Public base URL	https://lic2.ritzy.net	The externally reachable URL. Accept the default on the live server; use http://localhost:<port> only for a local test. Used for PayPal returns and given to installs as the heartbeat URL.
   Allowed console origin(s)	the public URL	Same HTTPS URL. Comma-separate if more than one.
   Enable PayPal payments?	No	N unless you are taking card payments now; you can enable it later in .env.
   Enquiry intake key	blank (intake off)	The shared key the website sends with each quotation request. Type generate for a random one (it is printed — copy it into the website's ritzy-config.php), or leave blank to keep the intake off.
   Intake posts accepted per minute	30	Asked only when a key is set. Keep 30.
   Is this server proxied by Cloudflare?	Yes	Y for lic2.ritzy.net. The client address is then read from CF-Connecting-IP, only for requests from Cloudflare's edge.

The installer generates ADMIN_JWT_SECRET automatically, installs dependencies, registers and starts the Windows service ritzy-license (through NSSM, like Ritzy One's ritzy-api), opens the firewall port and runs a health check. Run install.cmd and deploy.cmd as Administrator.

3.2 First login — do all four

Browse to the console (the installer prints the URL) and sign in with the bootstrap admin.

1. Change the password — minimum 6 characters. Editing BOOTSTRAP_ADMIN_PASSWORD in .env afterwards does nothing; it is only read when the database is empty.
2. Enable two-factor in Settings.
3. Settings → Licence signing key → Generate new key pair. The private key is shown once — copy it into your password manager now. Until this is done the console cannot sign anything (canSign=false).
4. Back up the data\ folder (see §12).

3.3 Put it behind HTTPS (any internet-facing server)

Customers post their licence tokens to this server, so it must not be plain HTTP in production. A ready nginx config ships in the bundle as nginx.sample.conf:

1. Replace licenses.example.com in three places (the two server_name lines and the certificate paths).
2. Install it to /etc/nginx/sites-available/ritzy-license.conf, symlink into sites-enabled.
3. sudo certbot --nginx -d licence.yourdomain, then sudo nginx -t && sudo systemctl reload nginx.
4. Set PUBLIC_BASE_URL and CORS_ORIGIN in .env to the HTTPS URL and restart: Restart-Service ritzy-license (elevated PowerShell).

It proxies to http://127.0.0.1:4100. On Windows, mirror the same thing with IIS ARR + URL Rewrite.

3.4 Confirm it is healthy

healthcheck.cmd https://licence.yourdomain

Exit code 0 = healthy. It prints the running version and canSign, and checks the Windows service ritzy-license is running. With no argument it tests http://localhost:4100. It is a drop-in for a Windows Scheduled Task.

4Part B — Prepare the customer server

4.1 PostgreSQL 18

Ritzy One keeps every company in one PostgreSQL database, kept apart by Row-Level Security. Nothing has to be installed beforehand: install.ps1 installs PostgreSQL 18 with the EDB installer in silent mode (server and command-line tools only), puts its data folder under the base folder (<RITZY_ROOT>\PostgreSQL\18\data), sets the postgresql-x64-18 service to start automatically, generates two passwords and writes them into packages\api\.env as PG_URL (the postgres superuser) and PG_APP_URL (ritzy_app). On its first start the app creates the database, the schema and the ritzy_app login itself.

4.2 Understand RITZY_ROOT before you install

Getting this wrong is the single most common installation mistake. RITZY_ROOT is the base folder — not the Ritzy folder inside it. Default C:\Ritzy Solutions:

So for the default, RITZY_ROOT=C:\Ritzy Solutions — never C:\Ritzy Solutions\Ritzy.

4.3 Ports

The installer opens these inbound TCP rules. Confirm nothing else is using them:

5Part C — Install Ritzy One

1. Extract RitzyOne-deploy.zip to the install folder, e.g. C:\RitzyOne.
2. Open PowerShell as Administrator in that folder and run:

   powershell -ExecutionPolicy Bypass -File install.ps1

3. Answer the prompts as they come:

   Prompt	Answer
   Enter the Ritzy base folder path	The RITZY_ROOT base folder — see §4.2. Only asked if it can't be auto-detected.
   Password of the PostgreSQL superuser 'postgres'	Only asked when PostgreSQL 18 was already installed. A new install generates it.
   Overwrite existing nginx.conf?	Y on a new server

What it sets up

• PostgreSQL 18 and its service, when missing (§4.1).
• Dependencies, and the API's .env at packages\api\.env with PG_URL / PG_APP_URL and a random JWT_SECRET.
• PM2 process ritzy-api plus Windows services ritzy-api and nginx (via NSSM) so it survives reboot.
• nginx (downloaded if absent) and the four firewall rules.
• The scheduled task Ritzy PostgreSQL backup: a daily pg_dump -Fc at 01:30 into <RITZY_ROOT>\Backups\PostgreSQL, 14 days kept.
• Nothing else for a fresh site: an empty database puts the app into first-run mode.

Confirm the API is live and running the build you expect:

curl http://localhost:3001/api/version

6Part D — Create the first company

On a server with no companies yet, the login page replaces the sign-in form with a Set up Ritzy button.

1. Browse to http://<server>/ and click Set up Ritzy.
2. Enter today's support password when prompted.
3. Complete the wizard:

   Field	Notes
   Company code	1–5 characters, A–Z and 0–9 only. Identifies the company in the database and cannot be changed later.
   Company name	Stored upper-case.
   Base currency	Drives the tax/registration caption (AUD→ABN, BHD→CR.No., SAR→VAT No., AED→TRN).
   Financial year	Start/end month and year. Must span 1–24 periods; one PERIODS row is created per month.
   Administrator login	The customer-facing admin account. DBA is reserved and will be rejected — use ADMIN.

4. Click Create Company. It adds the company to the database and seeds it: financial year, periods, numbering, starter charges and user groups.
5. The wizard's last page is Activation. Paste the activation code here and click Activate — it does exactly what Part E below describes, so a server set up this way is licensed before you ever sign in. Leave it blank and click Finish to license later from the DBA Console.

7Part E — Licence the installation one code

Licensing is now a single field. You mint a short code on the License Server and the DBA pastes it into the install.

7.1 On the License Server (vendor)

1. Customers → New customer. The Customer code you set here is the stable id embedded in every token and used by billing and revocation — choose it carefully, e.g. ACME.
2. Open the customer → Create subscription: seats, add-on modules, cycle, amount, start date, grace days. Saving mints the signed token automatically.
   Seats

   Seats are concurrent devices (browsers), pooled globally. The Customer Statement PWA is exempt, and the DBA account is seat-exempt so support can always get in. Avoid 1-seat tokens outside a lab — they lock ordinary users to a single browser.
3. In the Activation code card, click New activation code:

   Field	Guidance
   Times it can be used	1 for a single install. Use 0 (unlimited) only when a customer is rebuilding servers, and revoke it afterwards.
   Expires	Default 30 days. Leave empty for no expiry.
   Note	Internal, e.g. “emailed to their IT on 26 Jul”.

   The code is shown once in a dialog and copied to your clipboard. It looks like RTZY-4K7M-9XQP-2WDF.
4. Send the customer the code. That is all they need — no key file, no public key, no PEM.

7.2 On the customer install

Any administrator can also do this without the DBA Console or the support password: click Activate beside the licence message at the top of the screen and paste the code (after the trial ends an administrator's sign-in opens straight onto an Activate Ritzy screen). That path uses the License Server the install is already configured for. The DBA Console route below is the one to use when the server URL has to be set.

1. Sign in as DBA and open Tools → DBA Console → Licensing.
2. Enter today's support password in the header.
3. Paste the code into Activate this installation and click Activate. It activates against https://lic2.ritzy.net unless the install was pointed at another License Server; only when the URL was deliberately cleared does a second field appear for it (it is remembered afterwards).

That one action does all of this:

1. Fetches and trusts the vendor's public key.
2. Pulls the customer's current signed licence and verifies it against that key.
3. Saves the heartbeat URL so renewals, suspensions and revocations flow automatically from now on.
4. Installs each company's own licence against that company — billing is per company database (Company ID + Company Code), so every subscribed company gets the key billed for it. A company Ritzy has no subscription for stays unlicensed; ask Ritzy to add it.
5. Switches enforcement on.

7.3 Confirm

Hard-reload the browser (the badge caches per page load). The header badge should read a green Licensed; hover it for plan, seats and expiry. The Licence on <company> card shows the customer, seats, modules and validity.

8Hand-over checklist

Walk this before you call the installation done.

• /api/version returns the build you deployed
• Dashboard loads on port 80; both PWAs load on 8081 and 8082
• Windows services ritzy-api and nginx are Running and set to Automatic
• The server survives a reboot — actually restart it and re-check
• The company appears in the login dropdown and ADMIN can sign in
• The built-in DBA password has been changed from the default
• Licence badge is green Licensed, with the right seats and modules
• Enforcement shows on in DBA Console → Licensing
• The Ritzy PostgreSQL backup task has run once (Task Scheduler → Run) and a .dump is in <RITZY_ROOT>\Backups\PostgreSQL; that folder is copied off the server
• Customer has the ADMIN credentials — and not the DBA ones

9Offline / air-gapped installs

When the install genuinely cannot reach the License Server, use the manual path under Advanced / offline setup on the Licensing tab. The order matters here — this is exactly what the activation code exists to avoid getting wrong.

1. On the License Server: Settings → Copy public key, and issue the customer a key (the customer's Issue stand-alone key, or the subscription's Download .lic).
2. On the install: Advanced / offline setup → Trusted public key → paste the PEM → Save pasted key. Do this first.
3. Install a key by hand → paste the token or upload the .lic. A key names its company and installs into that company's database only; issue one per company.
4. Switch Enforcement on.

An air-gapped licence cannot be suspended or renewed remotely — it simply ends at validTo plus grace. Re-key by repeating step 3 with a fresh .lic.

10Settings reference

Customer install — packages\api\.env

License Server — .env

11Troubleshooting

“This key could not be verified” when installing a key

The token's signature doesn't match the public key this install trusts. Compare fingerprints — curl https://<license-server>/api/license/public-key against the one on the Licensing tab. If they differ, re-trust the key (or just use an activation code, which does it for you). If they match, the token was signed before a key-pair rotation — re-issue the customer's key.

“Subscription starts on <today>” and login is blocked

A timezone bug in builds before license-tz-validity-2026-07-26: date-only bounds were compared against UTC midnight, so anywhere ahead of UTC (Australia, the Gulf) a licence starting today read as not-yet-valid all morning. Check /api/version and upgrade.

“That activation code is not valid”

Deliberately uniform — it means unknown, expired, revoked or already used. Open the customer on the License Server and read the code's real status in the Activation code table, then issue a new one. (Single-use codes are the default, so a second attempt on the same code always fails.)

“No licence has been issued for this account yet”

The code is valid but the customer has neither a subscription nor an issued key. Create the subscription first, then activate.

“Too many activation attempts” (HTTP 429)

Brute-force throttling, 10 attempts per minute per IP. Wait a minute.

A renewed subscription isn't picked up

Renewals arrive on the hourly heartbeat, and on login when a licence would otherwise block. Check that the install has a heartbeat URL and enforcement on. If the subscription was renewed on the server but the install is offline, it stays on its old token until it can reach the server again.

Locked out of the License Server console

reset-admin.cmd                          :: list admins
reset-admin.cmd admin "NewPassw0rd"      :: reset a password
reset-admin.cmd admin "NewPassw0rd" --clear-2fa

It works with the service running.

Users can't log in — “maximum number of users”

The seat cap comes from the token when a licence is present. Raise seats on the subscription and save (it re-mints and delivers automatically), or clear stale sessions in DBA Console. DBA is always seat-exempt.

A module is missing from the menu

Usually it simply isn't in the token: edit the subscription, add the module, save — the new entitlement is delivered on the next heartbeat with no database change. The gated add-ons are Liner (LN), Marine (MA), Warehousing (WH), Inland Transport (TR), Shipchandling (SC), Payroll (E) and CRM (CR); Cargo (SP) and Accounts (AC) are core and always available.

The Cargo module still says “Shipping”

The module name lives in VISION.MODULENAME and older databases seeded it as “Shipping”. Run 027_cargo_module_rename.sql from the Upgrade tab. (The product itself remains Ritzy Shipping; only the freight-forwarding module is called Cargo, to distinguish it from Liner, Marine and Inland Transport. “Shipping Line” stays as-is — that is the ocean carrier, not the module.)

The app looks stale after an update

Hard-reload the browser. A cached bundle regularly masquerades as a bug.

12Backup & routine ops

Back up on the License Server

The licence database backs itself up: a gbak backup runs daily into data\backups\ (the newest 14 kept), and Settings → Database backup in the console backs up now, downloads, uploads and restores. A restore checks the backup first and takes a backup of the current database before replacing it, so it can be undone. Copy the .fbk files off the machine as well, with the rest of the data\ folder and .env:

Back up on the customer server

The nightly dumps in <RITZY_ROOT>\Backups\PostgreSQL\ (restore with pg_restore --clean --if-exists -U postgres -d ritzy <file>), plus <RITZY_ROOT>\Ritzy\System\ and packages\api\.env. The licence itself needs no special backup — re-activating restores it.

Everyday commands

pm2 status                     :: what is running
pm2 restart ritzy-api          :: after an .env change or update
pm2 logs ritzy-api --lines 100 :: recent API log
Restart-Service ritzy-license  :: License Server (vendor box, elevated PowerShell)
healthcheck.cmd                :: License Server health, exit 0 = OK

Updating an existing customer server

1. Extract the new RitzyOne-deploy.zip over the install folder.
2. pm2 restart ritzy-api.
3. Confirm /api/version shows the new build, and hard-reload the browser.

13Start over (wipe test data)

To repeat an installation test from a clean slate. Neither uninstaller deletes data by default, so the steps below are what actually clears it.

13.1 Customer server (Ritzy One)

Every company lives in one PostgreSQL database (default name ritzy). Dropping it and restarting the app gives an empty install at the first-run company setup (§6). uninstall.ps1 does not touch the database.

1. Stop the app: pm2 stop ritzy-api (or net stop ritzy-api where it runs as a Windows service).
2. Find the postgres password in PG_URL in packages\api\.env (postgres://postgres:<password>@localhost:5432/ritzy), then drop the database — use the name from PG_URL if it isn't ritzy:

   "C:\Program Files\PostgreSQL\18\bin\psql.exe" -h localhost -U postgres -d postgres -c "DROP DATABASE ritzy WITH (FORCE);"

   WITH (FORCE) closes any connections still open.
3. Start the app again: pm2 start ritzy-api (or net start ritzy-api). On start it uses PG_URL to create a new empty database, the schema and the ritzy_app login.

Keep packages\api\.env — it holds the PostgreSQL logins the app needs to rebuild the database. Optional extras:

13.2 License Server

From the License Server folder, in a Command Prompt as Administrator:

uninstall.cmd -Yes -PurgeData

This removes the Windows service ritzy-license (and any PM2 process or boot hook an older install left), the firewall rule, and deletes .env and the whole data\ folder: the licence database (LICENSE.FDB, and an old license.db if present), data\backups\ and the signing key pair. Run uninstall.cmd without flags to be asked about each step instead (data is kept unless you say yes).

• Add -RemoveDeps to delete node_modules\, dist\ and client-dist\ as well — but not on an extracted deploy zip, which ships dist\ prebuilt and cannot rebuild it; re-extract the zip instead.
• If LICENSE_FB_DATABASE pointed outside data\, delete that file yourself once the service is stopped.

Then run install.cmd again (§3). The first start creates an empty licence database and the bootstrap admin, and you generate a new key pair in Settings.