⚙️ Configuration

Pluggable backend: DatabaseType selects the store — mongodb (default), postgresql, or sqlserver — and ConnectionString points at the matching backend. The platform database is named by PlatformDatabaseName (default blazorblueprint-platform); each tenant gets its own database, auto-named TenantDatabasePrefix + the organisation name (bb-org-acme). On PostgreSQL both are schemas rather than databases, with hyphens mapped to underscores.

Both names are set once, at first deploy. TenantDatabasePrefix is read only when an organisation is created, and every read afterwards routes off the name stored on that organisation — so changing it renames nothing that already exists, it only affects organisations created later. It is capped at 23 characters (the 63-character database-name limit less the 40-character organisation-name limit), and because it is written straight into CREATE DATABASE DDL it must be lowercase letters, digits, - or _ only, starting with a letter. It must also not be a prefix of PlatformDatabaseName — otherwise an organisation could be given the platform database's own name. Any of these stops the host at startup rather than at the first organisation.

PostgreSQL exception: once Database:UseMigrations is on, PlatformDatabaseName must stay at its default. EF migrations are compiled code and carry the platform schema name inside them, so a renamed platform database would migrate into the original schema and leave the application reading an empty one. The host refuses that combination at startup. MongoDB and SQL Server are unaffected — there the platform name is a database, not a schema baked into a migration.

Production: Use MongoDB Atlas or a self-hosted MongoDB, PostgreSQL, or SQL Server instance with authentication.

What Redis carries — five things, not one:

• The shared cache tier and the cross-instance eviction bus, so a save on one instance is visible to the rest immediately rather than after a TTL.
• The SignalR backplane, so Blazor circuits and hubs work across more than one instance.
• The Data Protection key ring — which is why users stay signed in across a deploy, and why losing Redis loses every [Encrypted] field permanently. Back it up. See Security.
• The job streams that carry background work to the worker, under Messaging:Transport=Redis.
• The shared rate-limit, job-claim and webhook-dedupe stores, which are what stop a second instance handing an attacker a second full budget or double-processing a webhook.

Configure the shared auth cookie domain and external login providers. Set Cookie:Domain to your platform's parent domain (with a leading dot) so the auth cookie is shared across tenant subdomains. It is mandatory whenever Features:SubdomainOrganisations is on — which is how the base configuration ships: outside Development the Web host refuses to boot with that flag on and this value blank, rather than silently issuing host-scoped cookies that log users out on every organisation switch.

Provider setup: Create an app in the Facebook Developer Portal, Google Cloud Console, or the Azure Portal → App Registrations. Register your platform domain as the OAuth redirect URI:

• Facebook: Valid OAuth Redirect URI = https://yourdomain.com/signin-facebook
• Google: Authorized Redirect URI = https://yourdomain.com/signin-google
• Microsoft: Redirect URI = https://yourdomain.com/signin-microsoft (register as a Web platform in the Azure app registration). Uses the /common endpoint by default, so the button accepts both personal Microsoft accounts and work/school accounts.
• Facebook Data Deletion: Data Deletion Request URL = https://yourdomain.com/api/Facebook/DeleteUserData

Only one redirect URI per provider is needed — tenant subdomains route their login flows through the platform host automatically. Credentials from appsettings are seeded into the platform organisation's External Authentication settings during initial setup and can be managed via Platform → External Authentication.

Organisations on their own custom domain must register their own Facebook/Google/Microsoft app and configure it via Admin → External Authentication. OAuth credentials are domain-bound, so the platform's app will not work on a custom domain — the login page simply hides those buttons until the org configures its own. This page is only visible to organisations accessed through a verified custom domain; on the platform host and tenant subdomains, external auth is managed at the platform level.

Four providers ship: OpenAI, OpenRouter, Ollama and n8n. OpenRouter and Ollama are OpenAI-compatible and run through the same client, so "OpenAI support" understates it — you can point the whole AI surface at a local Ollama and never call a hosted API. Credentials are platform-shared (one set across every tenant) and managed at /Platform/ApiIntegrations; the keys below only set addresses and the optional auto-seed.

• Base URLs are config-only — they are deliberately not editable per integration in the admin UI. This is the key to set for a self-hosted Ollama or an OpenAI-compatible gateway on your own address.
• Only OpenAI and n8n auto-seed an integration row at first boot, and only when DefaultIntegration.Enabled is true and an API key is present. OpenRouter and Ollama are added by hand at /Platform/ApiIntegrations — until you do, they simply do not exist.
• Ollama needs no API key (RequiresApiKey = false); it just needs to be reachable at its base URL.
• Content moderation is OpenAI-only — the /moderations endpoint has no equivalent on the others. A deployment running Ollama alone has no moderation pass.
• API keys are encrypted at rest, and every call goes through the shared HTTP policy stack (timeout, retry, circuit breaker, per-provider rate limit, audit row).

Each organisation carries its own TimeZone (default UTC), set on its site settings. Timestamps are stored in UTC and presented in the organisation's zone — so a report boundary, a scheduled item or a daily bucket lands where that organisation's users expect it, not where the server happens to be.

Culture is pinned deployment-wide rather than left to the host OS. A Linux container without a LANG set otherwise falls back to the invariant culture, which quietly changes how dates, decimal separators and string comparisons behave — the kind of difference that shows up as a parsing bug in production and nowhere else. Pinning it means dev, CI and production agree.

A new organisation is seeded from a template row edited at /Platform/OrganisationDefaults: theme mode, theme colour, time zone, launcher and private-by-default. It is copied once, at creation — editing it later moves nothing that already exists.

MongoDB needs nothing here. On PostgreSQL or SQL Server there are two schema modes, and the choice is a boot-time gate rather than a preference:

With migrations on, the DbMigrator applies EF migrations to the platform database and to every tenant. History is per-tenant, so tenants migrate independently. Run it as a gated one-shot ahead of the app — the shipped pipelines already do, and a failure blocks the deploy before the running app is touched.

Individual organisations can connect their own OpenID Connect identity provider (Okta, Auth0, Entra ID, etc.) via Admin → SSO (/Admin/Sso). Credentials are stored on the Organisation document so they can be resolved before tenant context is established.

Each configured organisation gets its own real authentication scheme — oidc-org:{orgId}, with callback /signin-oidc-org-{orgId} — registered at runtime from the organisation record. Users signing in via the org's SSO are matched to existing accounts by email or provisioned on first login.

When Features:CustomDomainOrganisations is enabled, an organisation admin can set a custom hostname on their organisation — one per organisation — and prove ownership via a DNS TXT record before the domain is considered verified. Requests on a verified custom domain resolve directly to that organisation.

An organisation admin sets the domain under Admin → Organisation Settings, then publishes a TXT record of the form {TxtRecordPrefix}{orgToken} on that domain. Verification is checked via public DNS resolvers (Cloudflare, Google) both immediately on request and by a background job that re-checks every few hours, with a small failure threshold before a previously verified domain is demoted.

The orgToken is deterministic: HMAC-SHA256(TokenHmacSecret, orgName + ":" + domain), truncated to 24 hex chars. Re-creating the same org with the same domain after a dev-environment DB reset produces the same token, so an existing DNS TXT record keeps verifying without touching the zone. Different orgs get different tokens for the same domain (because orgName is in the hash), which means a leftover TXT record from a previous tenant of a domain does not let a different org auto-verify. TokenHmacSecret is required — set it to a long random string (32+ chars of entropy) so tokens can't be pre-computed without the secret. It fails closed: if the secret is blank, token generation throws rather than falling back to an unkeyed hash.

User account deletion is soft by default: a deletion request marks the user and blocks sign-in, but the account is only purged once the grace window expires. During the grace window the user can sign in to /Account/DeletionStatus and cancel the request. This also powers the Facebook Data Deletion Request callback at /api/Facebook/DeleteUserData.

One switch decides where background work runs. Messaging:Transport is either Redis — jobs are published to a Redis stream and executed by the background worker, with the answer handed back to whichever web instance is waiting — or InProcess, where the same handlers run in the web process. That is the whole difference between the multi-process and single-process shapes; there is deliberately not one flag per pipeline.

Two job streams, and the split matters. api:jobs:expiring carries work that is pointless once stale — AI generation, status polls, reads. api:jobs:durable carries work that must never be silently dropped: charges, refunds, outbound email, statutory filings. They are siblings, not a default and a variant. Which stream a job takes is decided by the handler's own max-age declaration, not by a config key — so shortening a staleness window here can never quietly move a queued refund onto the evictable stream. Each host logs the resolved durable-job list at boot.

MaxLen is not a memory budget being spent. Consumers delete each entry as they finish it, so steady-state depth is roughly the in-flight count. It is outage insurance: the point at which a write starts trimming the oldest entries — which, during a backlog, are the unprocessed ones. Size it against the worst worker outage you intend to survive.

MessageSigningKey is required under the Redis transport outside Development, and every host must carry the same value (32+ characters of entropy) along with the same Caching:RedisKeyPrefix. A job envelope carries the organisation id that drives tenant routing, so an unsigned stream would let anything with write access target any tenant. Each host logs a short fingerprint of the key and its resolved stream names at startup, so a mismatch is visible by comparing two logs rather than by noticing that nothing is ever processed.

Redis 6.2 or newer, and the instance carrying these streams must run maxmemory-policy noeviction: any allkeys-* policy evicts job streams under memory pressure, which loses queued work silently.

Who may create the platform organisation and the first platform admin, on a deployment that has none yet. Both lists ship empty and the token is generated per process, so out of the box setup is reachable from loopback or with the token the app logs when it refuses an attempt.

• Token — pin the setup token instead of using the generated one. Needed if you run more than one web replica, since a generated token lives in a single process.
• TrustedNetworks / TrustedProxies — addresses allowed to reach setup without a token. The deploy compose files set 172.16.0.0/12 here so first run in a container is one click; see Security → Initial setup for what that trusts.

All three stop having any effect once an organisation exists.

The Blazor Web app talks to the separate Application Service API (Services/BlazorBlueprint.InternalApi, default port 8081) using a JWT client-credentials flow. Three values, and all three ship blank — supply them by environment variable, container secret or dotnet user-secrets, never in a committed file. The client secret is one shared value written into both hosts: the Web app presents it, the API compares against it, so they must match.

• ServeMode — Proxy (default) streams every file through the app; Direct returns a time-limited signed URL instead. Only a member-visibility file on a cloud provider is ever redirected; GridFS and public files always stream. The signed URL bounds a copied raw link only — the stable /api/files/{id} link never expires.
• MaxFileSizeMb — enforced for seekable and non-seekable streams alike, so a chunked upload cannot slip past it.
• Cloud credentials are secrets. Supply them by environment variable or user-secrets, or enter them at /Platform/StorageSettings — never in a committed file.

One VAPID pair per deployment, not per organisation — there is no per-org concept to inherit, which is why push is absent from the platform-branding list above. Like storage, these are seed values read once into the platform settings row and managed at /Platform/PushSettings afterwards.

The shipped CSP is the one you will edit first. It allows 'self' plus the analytics host, so any third-party script, font, style or XHR endpoint you add — a chat widget, a map, a payment element, a CDN font — is blocked until you name its origin here. The symptom is a console-only CSP violation with nothing in the server log, so check the browser console first when an added script "does nothing".

Embedding is off everywhere by default. To let one route be framed on a customer's site — a plugin's support widget, say — list its path prefix in EmbeddableRoutePrefixes and put the allowed embedding origins in EmbedFrameAncestors as a space-separated CSP source list (https://customer-a.com https://*.customer-b.com). Only matched routes get the relaxed frame-ancestors and lose X-Frame-Options; every other route keeps the locked-down defaults. Either key alone changes nothing.

• RateLimiting:PermitLimitPerMinute — the global per-request budget for everything that is not a static asset, a Blazor/SignalR frame or a health probe. Partitioned by client IP and User-Agent, so it bounds one browser rather than one address. It is a DoS backstop; your edge proxy or CDN is the real control.
• AuthRateLimitPerMinute — the auth pages get their own, tighter, IP-only partition, precisely so that rotating the User-Agent cannot mint a fresh budget against a login form.
• Lockout — per-account lockout on repeated failures, counted in the shared rate-limit store so scaling out does not multiply an attacker's attempts.
• ForceHttpsScheme — leave on. Turn it off only for the rare deployment with no reverse proxy in front of it.

MaxLocalSeconds is the real bound on staleness when a cross-instance eviction broadcast is missed, so keep it well below the three durations above it. RedisKeyPrefix is a first-deploy decision: it is part of the Data Protection key-ring name, so changing it on a running deployment points the app at an empty ring — see Security, which also explains why the prefix is namespacing rather than isolation between two deployments sharing one Redis.

Every outbound provider call runs through this shared stack — timeout, retry, circuit breaker, per-provider rate limit and an audit row. Three of the shipped values are load-bearing rather than tuning: AI needs minutes, the health probe must have no breaker, and email must never retry, because a retried send is a duplicate email. The same rule applies to anything non-idempotent you add.

• Localization:DefaultCulture — pins currency and date formatting across every host and OS. It must be set: a Linux container with no LANG runs the invariant culture, which renders the generic currency box glyph instead of a pound or dollar sign. An unset or unrecognised value falls back to en-GB.
• Cors:AllowedOrigins — empty is the shipped state and means no cross-origin caller is allowed, which is correct for a Blazor Server app whose only API consumer is itself. Add an origin only if a browser client on another origin must call this host directly.
• AllowedHosts — "*" ships because the app resolves tenants by hostname and cannot know yours. Narrow it to your real hostnames once you know them; it is a cheap defence against Host-header games that your reverse proxy should also be doing.
• DataProtection:KeyRingPath — the no-Redis fallback (Lite sets /keys), and it must be a durable, backed-up volume. Leave it empty when Redis holds the ring.
• Database:SchemaVersionGate:Enabled — the per-tenant schema check on a relational backend. Leave it on: turning it off does not fix a schema problem, it just replaces a maintenance page with a raw relation does not exist on whichever page touches the missing table first.

Two sections in the shipped appsettings.json exist for the licensor's own marketing site. Nothing strips them automatically, so check them before your first deploy:

• Checkout:* drives the pricing buttons on /download. They ship blank on purpose — blank renders a disabled "Coming soon" placeholder rather than pointing your visitors at somebody else's checkout. Since the licence does not permit you to pass the template on as a template, the honest move for your own deployment is to delete /download, /licence and the marketing home content and put your own product pages there.
• Legal:ContactEmail is the address of whoever granted the licence, shown only on /licence when the licence file cannot be read. It is deliberately not your support address — /documentation/support reads DefaultOrganisationSettings:SiteEmail for that, because a deployment's support queries belong to whoever runs it. Leave it pointing at the licensor.