Skip to main content

Demo mode

DEMO_MODE turns an Invoicerr instance into a public demo: a fixed account, a realistic dataset rebuilt on a schedule, and every outbound send refused outright. It exists for exactly one purpose, letting a stranger try the product on the internet, and must never be set on a real, self-hosted install.

Never on a real instance

Turning DEMO_MODE on makes the demo account's e-mail and password unchangeable, refuses new sign-ups outright, and blocks every e-mail, e-invoicing transport, webhook, tax-authority declaration and payment checkout session this instance could otherwise send. None of that is what a real self-hosted operator wants. This flag is for the one instance at demo.invoicerr.app and nothing else.

What it does​

Every outbound send is refused​

Set DEMO_MODE=true and the following are refused at the lowest layer each one shares with every other caller: a transport or provider added later is covered automatically, because the refusal lives in the shared chokepoint, not in each caller.

WhatRefused in
Every e-mail (document sends, reminders, signature requests, OTP codes, client-portal invites, data exports...)MailService.sendMail/sendForCompany (backend/src/mail/mail.service.ts)
Every e-invoicing transport (email, PDP, Iopole, KSeF, SdI, SdI-PEC, A-Cube, Chorus Pro, Invopop, Billit, and any third-party transport registered later)TransportRegistry.register (backend/src/modules/documents/transports/transport-registry.ts)
Every outbound webhookWebhooksService.send (backend/src/modules/webhooks/webhooks.service.ts)
Every tax-authority declaration (Portugal's AT, and any provider registered later)DeclarationProviderRegistry.register (backend/src/modules/documents/reporting/declaration-provider.ts)
Every card/online payment checkout session (Stripe, Mollie, PayPal, and any provider registered later)PaymentProviderRegistry.register (backend/src/modules/documents/payments/payment-provider-registry.ts)

A refused action never looks like it worked: it returns a clear 403 naming what is disabled (DEMO_MODE_BLOCKED), never a silent success. A send that would reach nobody at all never gets as far as a chokepoint: a credit note that corrects no invoice has no client, so its Send is refused before it is numbered, on every install, demo or not.

Billing is forced off outright, independently of WARNING__ENABLE_BILLING_FOR_USERS__WARNING: no paywall, no seat gate, no Stripe plugin, whatever that flag happens to be set to in the same environment. See backend/src/modules/billing/billing-flag.ts#isBillingEnabled.

Self-hosted, local OCR on an uploaded received invoice is not blocked by DEMO_MODE: nothing leaves the instance as long as the OCR container itself runs inside the demo's own namespace, which is an infrastructure decision outside the product's own scope.

The demo account cannot be taken over​

While DEMO_MODE is on:

  • The account's e-mail and password can never be changed (POST /api/auth/change-email, POST /api/auth/change-password, and POST /api/auth-extended/set-password for an SSO-only account all refuse outright).
  • The account cannot be deleted.
  • The company cannot be deleted.
  • Sign-up is closed outright, refused server-side (backend/src/lib/registration-policy.ts#decideRegistration), even with a valid invitation code and even for the very first user. The sign-in page also hides its "Sign up" link.
  • API keys cannot be created or revoked.
  • SSO cannot be configured, and no domain can be claimed for it.

Every one of these is enforced server-side; the frontend only hides or disables the corresponding button as a convenience.

The banner​

Every authenticated page shows a sticky top banner: "Demo: data resets every 4 hours. Nothing you enter is kept or sent." The number of hours is DEMO_RESET_INTERVAL_HOURS (see Configuration), never part of the translated text.

Automatic sign-in​

A visitor with no session is signed in with the demo account and lands on the dashboard, with no click. Any route that sends a signed-out visitor to the sign-in page leads there, so opening the demo on any page works. The sign-in page makes the attempt once per visit, through the same sign-in call and the same error handling as the form: if it fails, the visitor stays on the sign-in page with the error shown and the form usable, never a spinner.

After an explicit sign-out (the account menu, /auth/sign-out, or the waiting-for-seat screen), the visitor lands on the sign-in page and is not signed straight back in. Every sign-out goes through frontend/src/lib/sign-out.ts, which records it in sessionStorage for the browser tab:

  • a reload of that tab stays on the sign-in page;
  • a new tab, or the same browser after the tab is closed, is a fresh visit and is signed in again;
  • a browser that refuses sessionStorage is never signed in automatically, since the page cannot tell whether the visitor just signed out.

The sign-in page​

The sign-in page shows a "This is a public demo" box above the form, drawn as a dashed ticket: the reset interval, the demo account's e-mail and password each with a copy button, and a Try it without an account button that signs in with that account in one click, through the same call as the automatic sign-in. A visitor who signed out can also type the credentials into the form by hand.

The e-mail, password and reset interval are served by the backend, never written into the frontend or into a translation: GET /api/legal/documents, the public endpoint that already carries demoMode, returns them as demo:

{ "demoMode": true, "demo": { "email": "demo@invoicerr.app", "password": "demo", "resetIntervalHours": 4 } }

Translations only carry the surrounding sentences, so a translation can never alter or drop the credentials. The password is public by design: the box prints it for anyone who opens the page.

Nothing of this exists outside demo mode

With DEMO_MODE off, demo is always null: no demo e-mail, password or interval is ever sent to a browser, nothing signs anyone in automatically, and neither the box nor the banner renders. There is no demo-only sign-in route to reach: the automatic sign-in uses the ordinary e-mail sign-in, with the credentials it was served.

The seed​

npm run demo:reset (backend/scripts/demo-reset.ts) rebuilds the demo dataset from scratch:

  • One company per supported country (defaultCountryPolicyCatalog.countries(), today DE, FR, IT, PL, PT, discovered at runtime, never hardcoded), each reachable from the single demo account through the company switcher.
  • For each company, at least two documents of every document type that country's own policy offers (defaultCountryPolicyCatalog.typesFor(countryCode), also discovered at runtime): quotes (one with named options, one manually accepted/"signed"), invoices in several states (draft, sent, overdue, partly paid, paid in full, and one credited for one line then paid for the balance), where the country's own law has a credit note, a sent one crediting one line of that last invoice and a draft correcting one line of the pending invoice (every seeded credit note corrects an invoice, so each has a client to be sent to), expenses, received invoices, a purchase order and a goods receipt. Every payment amount is read from the invoice's own settlement (VAT included), so no seeded invoice ends with an excess. Where the country has no credit note, the last invoice is simply paid in full too.
  • Company, client and article names, amounts, quantities and dates vary between resets: the generator takes a seed (backend/src/modules/demo/generators/rng.ts, a seedable PRNG), a fresh one drawn on every real reset, a fixed one in every test that exercises it.
  • Every generated document is valid for its country: numbering goes through the real numbering service, and every national identifier (SIRET for France, USt-IdNr for Germany, Partita IVA for Italy, NIP for Poland, NIF for Portugal) carries a real, checksum-valid value (backend/src/modules/demo/generators/identifiers.ts; identifiers.spec.ts runs each generator against several seeds and checks the result with this codebase's own offline validators). Which identifiers a demo party gets, and which algorithm fills each one, comes from the demoGenerator of each scheme in the country's own file (see Adding a country).
  • Every document is created through the real DocumentsService.runAction, never a raw database row, so country-policy compliance, field validation and numbering all come from the same code path a real user's own action would go through. Reaching "sent" status uses a numbering-only bypass (backend/src/modules/demo/seed-runtime/move-to-sent.ts) instead of the real send action, so a reset never depends on a working mail/transport configuration existing in whatever namespace it runs in.

The reset is safe while visitors are connected​

The reset never deletes before it rebuilds. It builds every new company for every country first, each one fully; only once every new company exists does it delete the old ones, in one final pass. A visitor connected mid-reset sees, at worst, a company switcher briefly listing more companies than usual, never fewer, never a half-built company with some document types present and others missing, and never a moment with no company at all. "Old" companies are never guessed or tagged: they are whatever company the demo account belonged to before this run started, since sign-up being closed makes the demo account the only account this instance ever has, so every company it belongs to is demo data, by construction.

Scheduling it​

The product does not schedule its own reset; that is an infrastructure decision. Run npm run demo:reset (tsx scripts/demo-reset.ts, the same "raw script, compiled src" pattern catalogs:release already uses, see that script's own header) from a Kubernetes CronJob on a 4-hour schedule (0 */4 * * *), against the demo namespace's own DEMO_MODE=true environment. A different schedule needs DEMO_RESET_INTERVAL_HOURS set to match, or the sign-in page and the banner will state the wrong interval. It is idempotent and self-contained: it creates the demo account if missing, reuses it otherwise, and needs no other process to be stopped first.

npm run demo:reset only resolves correctly against a built backend: ../src/... imports in scripts/demo-reset.ts need src to be compiled JavaScript, not raw TypeScript, because the script boots a real NestFactory.createApplicationContext, and tsx's own esbuild-based transpilation does not emit the decorator metadata Nest's DI reads (nest build's tsc/swc pipeline does). The production image already has this shape for free (Dockerfile copies dist/src to a directory named src, and scripts/*.ts to a sibling scripts), so npm run demo:reset runs there unmodified. Locally or in CI, first npm run build, then run scripts/demo-reset.ts from a working directory where a compiled src sits next to it, for example by copying the script into dist/scripts/ and invoking tsx from inside dist/.

Configuration​

See backend/.env.example for both settings.

VariableDefaultWhat it does
DEMO_MODEoffTurns the instance into the public demo described on this page.
DEMO_RESET_INTERVAL_HOURS4How often the reset job runs, in whole hours, as the sign-in page and the banner state it. Read only in demo mode; anything but a positive whole number falls back to 4.

The demo account's address and password are fixed (demo@invoicerr.app / demo, backend/src/modules/demo/demo-flag.ts): the reset script creates the account with them, and the sign-in page shows them from the same constants. Every blocked sender needs no per-transport configuration to stay blocked.