← All docs

Portal operations

Operational reference for src/DynDyn.Portal (the customer site) and src/DynDyn.AdminPortal (the back office) — two applications sharing the src/DynDyn.Portal.Shared Razor class library, one database, one artifacts volume and one licence signing key. See docs/portal.md for the build spec this implements. As of 2026-09-02 (branch feat/portal) the portal has organisations/roles, licensing and activations, release distribution (downloads + API tokens), an admin back office, and Stripe billing wired in — see the Licensing, Distribution and Billing sections below. Everything in this document applies to both applications unless a section says otherwise; "The back office is a separate application" below covers what differs between them.

Running locally

dotnet run --project src/DynDyn.Portal

With no ConnectionStrings:Portal configured, the app creates and uses a SQLite database at portal.db in the project's content root (Database.EnsureCreated() on startup — there is no SQLite migration history, only the Npgsql one). This is the default for local development and is what tests/DynDyn.Tests.Portal uses as well, via an in-memory SQLite connection.

EnsureCreated() creates the schema once and never migrates it, so a portal.db left over from before an entity change fails at startup with a bare SQLite error naming the missing column (for example SQLite Error 1: 'table organisations has no column named billing_email'). The local file holds nothing worth keeping — delete src/DynDyn.Portal/portal.db* and start again. Postgres deployments are unaffected: they run the migrations.

Running src/DynDyn.AdminPortal the same way (dotnet run --project src/DynDyn.AdminPortal) falls back to its own portal.db, next to its own project file, and the two applications would then disagree about every user and organisation in the system — the back office ships Portal:InitialiseDatabase=false, so it never even creates that schema itself, and starting it alone against an empty file fails every query. Point it at the customer app's database instead with Portal:SqliteFile (below), or use pwsh scripts/start-dev.ps1 -AdminPort <port>, which does this for you — see "Default development administrator".

Default development administrator

pwsh scripts/start-dev.ps1

starts src/DynDyn.Portal (the customer site) on http://localhost:5100 by default (-Port or -Urls to change it), waits for its /healthz to answer, then opens a browser tab. Sign in at /Identity/Account/Login — the "Email or username" field accepts either — with username admin and password admin: a seeded Identity user with the PlatformOwner role and a personal organisation, its password hash written directly so Identity's normal password policy is bypassed for the seed. Two-factor enforcement (Portal:EnforceTwoFactor, below) is off for this run only, so admin can reach /portal without first enrolling an authenticator.

Pass -AdminPort <port> to also start src/DynDyn.AdminPortal (the back office) as a second process, once the customer site's /healthz answers, against that same SQLite database (via Portal:SqliteFile, below) — see "The back office is a separate application" for why they need to share one. The two applications are genuinely separate: signing in as admin/admin on the customer site does nothing for http://localhost:<AdminPort>/admin — sign in there again with the same credentials, exactly as in production. -Watch runs whichever processes are started under dotnet watch instead of dotnet run; -NoBrowser skips opening the browser tab. The script stops any process left listening on the target port(s) from a previous run before starting, and stops everything it started on Ctrl+C.

Under the hood, for the customer site the script runs dotnet run --project src/DynDyn.Portal -c <Configuration> --urls <Urls> -- --environment Development --Portal:DevAdmin:Enabled true --Portal:EnforceTwoFactor false, and, when -AdminPort is set, for the back office dotnet run --project src/DynDyn.AdminPortal -c <Configuration> --urls http://localhost:<AdminPort> -- --environment Development --Portal:EnforceTwoFactor false --Portal:InitialiseDatabase false --Portal:SqliteFile <customer site's portal.db> --Portal:CustomerBaseUrl <customer site's base URL>. Portal:DevAdmin:Enabled and Portal:EnforceTwoFactor=false are Development-only: InitialisePortalDatabaseAsync (src/DynDyn.Portal.Shared/Hosting/PortalHostExtensions.cs), which both hosts call at startup, throws if either reaches any environment other than Development, so neither can reach a real deployment — see "Configuration keys" below.

Configuration keys

All keys below live under the Portal: section unless noted otherwise.

The back office is a separate application

/admin is not a mode of src/DynDyn.Portal — it is src/DynDyn.AdminPortal, a second ASP.NET Core host, its own process and its own deployable, built from the same src/DynDyn.Portal.Shared Razor class library (Data, Migrations, Features, Services, Security, Authorization, Options, Hosting, the shared _Layout and wwwroot, served at /_content/DynDyn.Portal.Shared/...) but with its own composition root. The customer host serves the marketing site, /portal and /api; the back office serves /admin and nothing else — no /portal, no /api, no /docs, no /legal, and no /Identity/Account/Register (its route selectors are cleared at startup, since nobody self-registers into the back office — platform-owner accounts are created out of band, see "First PlatformOwner bootstrap" below). / on the back office redirects to /admin; both hosts answer /healthz.

Each application signs in independently: its own login page, its own authentication cookie (portal.auth on the customer host, admin.auth on the back office), its own antiforgery cookie (portal.antiforgery / admin.antiforgery), and its own ASP.NET Core Data Protection application name (SetApplicationName("DynDyn.Portal") / SetApplicationName("DynDyn.AdminPortal")), so neither host can decrypt the other's session cookie. A session stolen from the customer site — the surface open to the internet at large — is worthless against the back office; a compromised customer process has no /admin routes mapped in it to reach at all. This is a blast-radius boundary on top of, not instead of, the existing authorization: /admin still requires the PlatformOwner role and mandatory two-factor (TwoFactorEnforcementPageFilter) exactly as before — an anonymous caller still gets a 302 to /Identity/Account/Login, not a free pass. The split narrows which process /admin runs in; it does not replace who may use it.

What the two processes still share: one Postgres/SQLite database and migration history (Portal:InitialiseDatabase above says which process owns bring-up), one artifacts volume (Portal:ArtifactRoot — read-write from the back office, which uploads release artifacts at /admin/releases/create, and read-only from the customer host, which serves them), and one licence signing key (Licensing:SigningKeyPemFile).

Deployment. docker/portal.Dockerfile builds both applications from one Dockerfile (--target portal / --target admin), sharing the restore and build layers so the two images only differ in their last stage. docker/docker-compose.portal.yml runs them as the portal and admin services alongside postgres; admin waits on portal's health check so schema bring-up only ever happens once, before the back office starts querying it. docker/admin.env, loaded by the admin service only and layered after docker/portal.env, carries the handful of settings that must differ between the two hosts — Portal:PublicBaseUrl above all, since the back office has its own hostname — see docker/portal.env.example for the full list. docker/.env's PORTAL_PUBLIC_BASE_URL feeds the customer site's origin to the admin service as Portal:CustomerBaseUrl. Neither service publishes a host port by default; the repo's real deployment sits behind Traefik, and the compose file's commented-out labels: block gives the back office its own router, on its own hostname, behind an IP allow-list — publishing it on the same open listener the split exists to get it off of would undo the whole point.

Locally, pwsh scripts/start-dev.ps1 -AdminPort <port> starts both processes against one SQLite database — see "Default development administrator" above.

First PlatformOwner bootstrap

There is no admin UI to grant the PlatformOwner role, by design (no impersonation, no privilege escalation surface in phase 1). Instead:

1. Register a normal account through /Identity/Account/Register using the email you intend to be the platform owner.
2. Set Portal:BootstrapOwnerEmail to that same email (environment variable Portal__BootstrapOwnerEmail, or the equivalent config key for your deployment).
3. Restart the app. BootstrapOwnerRole.EnsureAsync runs on every startup, finds the user by email, creates the PlatformOwner role if it doesn't exist, and adds the user to it if not already a member. It is idempotent and safe to leave configured permanently.
4. Sign out and back in (or wait for the next login) so the new role claim lands in a fresh authentication cookie, then enable two-factor authentication at /portal/security — /admin requires both the PlatformOwner role and 2FA.

If Portal:BootstrapOwnerEmail is unset, no user is ever promoted and /admin is unreachable by anyone. That is the expected state for a fresh deployment until an operator configures it.

Licensing

Config keys live under Licensing: (Features/Licensing/LicensingOptions.cs):

The KMS signer is a stub, not a missing feature: setting Licensing:Signer=Kms selects KmsPayloadSigner, whose KeyId, PublicKeyPem and Sign members all throw NotSupportedException. The app boots fine either way — the exception only fires the first time something actually needs a signature — but no licence, activation code or revocation list can be issued/signed while Signer=Kms until a real KMS-backed implementation replaces the stub.

Behaviour, verified against Features/Licensing/*.cs:

• Activation (POST /api/v1/activations, and /portal/activations for Owner/Admin/Developer): a fuzzy 3-of-5 fingerprint match (MachineFingerprint.Matches) against any live activation sharing the licence's LicenseId reuses/renews that activation without consuming a seat; a genuinely new fingerprint is blocked with 409 once live activations reach the row's MaxInstances. Deactivation counts toward MaxRehostsPerYear the same way, across sibling rows.
• GET /api/v1/licenses/current takes Authorization: License <key>, returns status (Active/Lapsed/Revoked), whether the presented key is still the current one for that LicenseId (a re-issue mints a new key on the same LicenseId and revokes the old row), edition, seats used/total and the feature list.
• Self-service licence management (/portal/licenses) — generate (evaluation or from-subscription), re-issue, revoke — is restricted to Owner/Admin only (Pages/Portal/Licenses/Index.cshtml.cs's ManageRoles). docs/portal.md §4 describes a Developer self-generate path ("Developer may generate one for themself if seats are free"); the code does not implement it — see docs/portal.md §9.
• One evaluation licence per organisation, ever. LicenseService.HasEvaluationLicenseAsync checks Edition == Evaluation for the org regardless of status, so even a revoked evaluation licence permanently blocks issuing another one for that org.
• Manual admin issuance (/admin/licenses/issue, PlatformOwner + mandatory 2FA) bypasses every business rule enforced elsewhere in LicenseService — not just the seat cap — per that service's own doc comment: it is the intended override path.
• Automatic issuance from Stripe subscriptions. SubscriptionLicenseIssuer (Features/Licensing/SubscriptionLicenseIssuer.cs) is registered as an ISubscriptionLifecycleHandler alongside any other handler and runs on every subscription change the billing webhook processes (see Billing below):
  • The first time an org's subscription becomes active or trialing on a licensable tier (Starter/Pro/Enterprise — Community carries no entitlement), it issues a licence via the same LicenseService.IssueManualAsync path the admin form uses, with seats from Subscription.Seats and expiry at Subscription.CurrentPeriodEnd. trialing is treated identically to active — a licence is issued for the full length of a Stripe trial, not only once the first payment succeeds.
  • A later active/trialing change (tier/seat/period-end moved) updates that same licence row in place — no key rotation, since an already-installed key must keep resolving — and never issues a second licence for the same subscription.
  • canceled lets the existing licence lapse at the subscription's already-known period end (sets ExpiresAt) rather than revoking it immediately.
  • past_due and any other status this handler doesn't recognise: no change — a dunning subscription never revokes access.
  • If Organisation.IssuancePaused is set (via a Stripe dispute — see Billing), issuance/updates are skipped entirely and an audit entry (licensing.issuance_skipped) is written instead.

Distribution

Config keys live under Distribution: (Features/Distribution/DistributionOptions.cs):

Behaviour, verified against Features/Distribution/*.cs:

• Download (GET /api/v1/releases/{version}/{kind}/{rid}/download) accepts a Bearer token with the download scope or an authenticated portal session with active org membership — every download is recorded as a DownloadEvent either way, so the endpoint always needs an identity. When the active store supports presigning (Store=S3), the response is a redirect to a presigned URL; FileSystemArtifactStore always returns null from TryGetPresignedUrl, so on Store=FileSystem the endpoint streams the file directly with HTTP range support instead.
• Publish (POST /api/v1/releases, multipart) requires a Bearer token with the releases:publish scope — deliberately no session/PlatformOwner fallback, because minimal-API routes sit outside UseAntiforgery(). The Admin UI (/admin/releases/create) instead calls IReleaseService directly and always creates the release unpublished (IsPublic=false); ReleaseService has separate PublishAsync/YankAsync methods for the explicit state change. The public listing (GET /api/v1/releases, anonymous) only returns releases with IsPublic=true && !IsYanked, with an optional ?channel= filter (stable or preview).
• API token scopes in use (ApiTokenScopes.Known): download, activate, releases:publish, admin, licenses:read.
• Token management (/portal/tokens) is Owner/Admin only; every org role can view existing tokens (prefix/last-four only) and download releases.

Billing

Config keys live under Stripe: (Features/Billing/StripeOptions.cs):

Webhook endpoint: POST /api/v1/billing/webhook (anonymous, antiforgery disabled, raw body + Stripe-Signature header). Idempotency is a StripeEvent ledger row keyed by Stripe's EventId: a delivery whose row already has ProcessedAt != null && Error == null is short-circuited with a plain 200 and nothing is reprocessed.

What happens when something throws, from StripeWebhookHandler.cs:

Event application (the subscription upsert plus the audit-log write) runs inside a database transaction. If that work — or the following save/commit — throws, the transaction is rolled back (none of that event's DB writes persist), StripeEvent.Error is set to the exception message with ProcessedAt left/reset to null, and the handler returns 500. Because the idempotency check requires both ProcessedAt != null and Error == null, Stripe's automatic retry of that same event delivery does not short-circuit — it re-enters the handler and reprocesses the event from scratch (the upsert logic is written to be safe to repeat).

Registered ISubscriptionLifecycleHandlers (e.g. SubscriptionLicenseIssuer, see Licensing above) run only after that transaction has already committed, so a handler throwing does not roll back the Subscription/StripeEvent write — it stays committed with ProcessedAt already non-null. A handler failure instead sets just StripeEvent.Error (leaving the already-committed ProcessedAt alone) and the endpoint still returns 500. Since Error is now non-null, the same idempotency check still fails on retry — so a retry after a handler failure also does not short-circuit: it re-runs the whole event application again (a harmless repeat of an idempotent upsert) and re-invokes every registered lifecycle handler, including ones that already succeeded on the first attempt.

Other behaviour:

• One live subscription per organisation (Subscription.OrgId is a unique index). StartCheckoutAsync opens a new Stripe Checkout session only when the org has no subscription in a live status (active/trialing/past_due/unpaid); otherwise a tier change is applied as a price change on the existing subscription (ProrationBehavior=create_prorations), not a new subscription.
• customer.updated keeps Organisation.BillingEmail in sync from Stripe.
• charge.dispute.created sets Organisation.IssuancePaused = true — this only pauses future licence issuance/updates (see Licensing above); nothing already granted is revoked.
• /portal/billing: Owner/Admin/Billing roles can start checkout, open the Stripe billing portal, cancel or resume; every org role can view the current plan.
• /admin/stripe-events (PlatformOwner, read-only) lists the raw ledger, capped at the 200 most recent rows by ReceivedAt — useful for diagnosing a stuck or failed webhook without DB access.

Release publishing from CI

Implemented via the Distribution feature above: a CI job (or any automation) publishes a release by calling POST /api/v1/releases with a Bearer token carrying the releases:publish scope — the same mechanism a human uses via /portal/tokens to create that token. There is no separate "CI publishing" code path; it is the same endpoint DistributionAuthFilter gates for any caller. A release created this way starts unpublished (IsPublic=false); making it visible on the public GET /api/v1/releases listing is a separate PublishAsync step (currently exposed only through IReleaseService, i.e. from the Admin pages or by extending them — there is no POST /api/v1/releases/{version}/publish endpoint yet).

Key rotation

Licence/revocation-list signing key custody is Licensing:SigningKeyPem / Licensing:SigningKeyId / Licensing:TrustedKeys (see Licensing above), not a portal-specific mechanism. To rotate: generate a new key, deploy it as Licensing:SigningKeyPem with a new Licensing:SigningKeyId, and add the old KeyId → its public key to Licensing:TrustedKeys so licences already issued under the old key keep verifying. There is no in-app rotation UI or automation — this is an operator procedure against the config values above. The Licensing:Signer=Kms path (intended to source the key from a real KMS instead of a config value) is a stub — see Licensing above — so today every deployment necessarily uses the PEM signer.

Health check

GET /healthz (AddHealthChecks() / MapHealthChecks("/healthz") in Program.cs) — no checks are registered against it yet, so it currently reports healthy whenever the process is up and answering HTTP requests. docker/portal.Dockerfile adds a container HEALTHCHECK that curls this endpoint every 30s.

Known gaps

Deliberate scope cuts and known limitations, tracked here per the "every gap needs a line here" rule rather than as inline TODOs:

• The admin image is not built by CI. .gitlab-ci.yml builds only the customer image (the Dockerfile's last stage, portal) through the shared template ci/build-image.yml of DynDyn.Servers, which has no --target support, so the admin image (--target admin) is not published and the back office is not deployed to p360. The fix is an optional TARGET variable in that template (docker build --target "$TARGET"), owned by the DynDyn.Servers repo; once it exists, add a second extends: .p360_build_image job with TARGET: admin and IMAGE_NAME: admin.
• No team members at all. The portal is single-seat: an organisation has exactly one member, its Owner, for its whole life. IOrganisationService has no add/change-role/remove/transfer operation any more — CreatePersonalOrganisationAsync (run once, at registration) is the only code path that ever writes a Membership row (docs/portal.md §9). This isn't a gap to fill later; it's a deliberate product decision.
• Most default Identity UI pages are unstyled. AddDefaultUI() supplies the packaged Razor Class Library pages for login/2FA/manage-account under /Identity/Account/.... No Bootstrap or jQuery assets are bundled, so those pages render with browser-default styling rather than the site's own design system (wwwroot/css/site.css). The one exception is /Identity/Account/Register, which is overridden in-project (Areas/Identity/Pages/Account/Register.cshtml) purely so a new account gets a personal organisation and an Owner membership (IOrganisationService.CreatePersonalOrganisationAsync) — it picks up the site layout as a side effect of that override, not as a deliberate styling pass; every other packaged page (login, 2FA setup, manage account, forgot password) is unstyled.
• No email sender. NoOpEmailSender (Services/NoOpEmailSender.cs) satisfies the packaged Identity UI pages' IEmailSender dependency by logging instead of sending. Password reset and email-confirmation links are never actually delivered.
• The KMS signer is a stub. Licensing:Signer=Kms boots the app but throws NotSupportedException on every signing operation — see Licensing above. Only the PEM signer is usable today.
• No impersonation, no SSO. Both remain out of scope per docs/portal.md §9. PlatformOwner admins debug customer issues by querying the DB directly or reading /admin/audit; there is no "log in as this org" feature. Organisation.SsoConfig exists as an unused, reserved column.
• The Postgres migration is generated but has limited real-database exercise. Migrations/InitialCreate (and any migrations layered on it since) is generated with dotnet ef migrations add against the Npgsql design-time factory (Data/PortalDbContextFactory.cs) and runs via Database.Migrate() at startup when ConnectionStrings:Portal is set. Local/dev/test all default to SQLite EnsureCreated() instead, which does not exercise the migration path at all — docker/docker-compose.portal.yml (Postgres 17) is the primary way to exercise it before a real deployment.
• No .gitlab-ci.yml stage runs dotnet ef database update (or any equivalent) against a real Postgres. build:image builds the customer image from docker/portal.Dockerfile (and pushes it from v* tags), but nothing in CI exercises Database.Migrate() against Postgres before a deployment does — docker/docker-compose.portal.yml (Postgres 17) is the primary way to exercise that path today, and only locally.