Deployment and security

This is the operator checklist for an Adonia panel. It complements the executable security conformance map; it does not replace an application threat model or AdonisJS deployment guidance.

Install and inspect

Install through the supported configure hook, not by copying files:

node ace add @adonia/core
node ace adonia:doctor

The provider @adonia/core/providers/adonia_provider must remain in adonisrc.ts. The generated start/kernel.ts entries for adonia.panel-access and adonia.tenant are ejection seams for host routes; Adonia also applies its own middleware instances to panel route groups. Keep the normal AdonisJS session, auth, Shield/XSRF, body limits, and proxy middleware enabled.

Reverse proxy and hosts

Terminate TLS at a trusted proxy and configure AdonisJS proxy trust so secure cookies, scheme, host, and generated absolute URLs reflect the public request. Allow only intended hosts. Domain or tenant-mounted panels must be present in Vite server.allowedHosts during development. Configure HMR’s public host when the browser cannot reach the server’s internal hostname.

For :tenant.example.com, provision wildcard DNS and TLS deliberately. Never derive a redirect or switcher target from an unvalidated Host header.

Sessions and XSRF

Host-only cookies are the safest default and isolate subdomains. Cross-subdomain SSO requires an intentional apex session and XSRF domain such as .example.com, Secure, HttpOnly for the session cookie, an appropriate SameSite policy, and matching Shield XSRF configuration. Re-run the doctor after changing domains:

node ace adonia:doctor --only=cookie-domain --only=shield-xsrf --only=vite-allowed-hosts

Every panel route except the configured login flow uses the guard, panel-access middleware, and tenant middleware when active. JSON endpoints use the same stack and Cache-Control: no-store. Do not put authenticated panel responses behind a shared cache.

Database and tenancy

Run migrations before serving traffic, including adonia_action_events and any action-batch/plugin tables in use. Tenant panels fail boot when a resource omits static tenantScope; keep unscoped-resources in deployment checks. Database roles should have only the schema privileges the application needs. Backups, point-in-time recovery, and retention for action events are application responsibilities.

Actions and CRUD events scrub declared sensitive fields, but application code must still avoid placing secrets in labels, exception messages, custom telemetry, or plugin notifications.

Uploads, imports, and exports

Use private object storage for uploads and generated exports. Serve downloads through short-lived signed URLs. Enforce MIME, extension, byte, row, cell, and error-count limits before expensive parsing; scan uploads according to your risk model. Never use a user-supplied filename as a storage path.

Import/export workers and action workers must receive the same panel, actor, tenant, resource, parent, and target identity that was authorized by the web process. Treat queue payloads as untrusted serialized input and preserve idempotency. Use a real shared queue and durable job/artifact stores for large exports; local file stores are single-host deployment boundaries.

Secrets and observability

Keep session, XSRF, storage-signing, queue, database, search, and telemetry credentials in the platform secret store. Rotate them without committing values to Adonia config or generated manifests. Restrict telemetry payloads to identifiers and timings; unknown-component telemetry intentionally excludes values, records, form state, and descriptor props.

Review E_ADONIA_* startup failures, plugin-hook errors, authorization denials, queue failures, and doctor results before promotion. Redact stack traces in user responses while retaining correlated server logs.

Pre-deploy commands

Run the repository’s normal typecheck, tests, security suite, docs checks, and bundle gate in CI. For the application deployment itself, at minimum run:

node ace migration:run --force
node ace adonia:doctor

Do not infer launch readiness from compiled documentation snippets: they verify TypeScript shapes only. Use the linked conformance reports for observed accessibility and performance evidence, and record environment-specific smoke results separately.