Configuration

The DMS module reads one config object — the config block you give @antelopejs-private/cms in your antelope.config.ts (Project setup). The reference below covers every key and its default. All keys are optional; a bare config: {} runs with the defaults.

"@antelopejs-private/cms": {
  source: { /* … */ },
  config: {
    apiBaseUrl: "http://localhost:5010",
    clientBaseUrl: "http://localhost:3001",
    homepage: "/form/form-simple",
    meta: { title: "Acme Admin", description: "Internal operations dashboard" },
    auth: {
      jwtSecret: "…", // the DMS's session-token signing secret — set a strong value in production
      mustValidateEmail: true,
    },
    realtime: { driver: "auto" },
    htmlRender: { renderEndpoint: "http://localhost:3001/api/html/render" },
  },
},

Top-level options

auth — tokens, validation, sanitization

These settings drive the Built-in authentication flow. Lifetimes are in milliseconds.

auth.oauth — login providers

Precoded providers (github, google) turn into a "Continue with …" button on the login and signup screens. A provider stays disabled — and invisible — until the instance supplies both credentials, so this block is entirely opt-in.

auth: {
  jwtSecret: "…",
  oauth: {
    providers: {
      github: { clientId: process.env.GITHUB_CLIENT_ID, clientSecret: process.env.GITHUB_CLIENT_SECRET },
    },
    allowAccountCreation: true,
  },
},

Register <callbackBaseUrl>/auth/oauth/<provider>/callback as the authorization callback URL in the provider's application settings.

The browser-facing OAuth routes are rate-limited to 10 flows per minute per client, enforced by the frontend server (each route carries its own 10-hit budget, so a full start + callback flow spends one of each). What identifies a client: by default, the socket address only — x-forwarded-for is never trusted, since any caller can write it; behind a shared proxy this means clients share one budget until you opt in. Deployments with a trusted reverse proxy directly in front set oauth.trustProxy: true, and the limit then keys on the forwarded entry that proxy itself appended (the last one). Relevant mostly with allowAccountCreation on, where the flow would otherwise be an unthrottled account factory.

Account linking rules. A provider account already bound to a user always resolves to that user. Otherwise, an account holding the same e-mail is only adopted when the provider marks that e-mail verified and the local account is validated — control of the mailbox is the single prerequisite, the same bar password recovery sets. Anything else is refused rather than linked silently. Two-factor authentication is unaffected: an OAuth login on a 2FA-enabled account still runs the challenge before a session is issued.

Signing in with a provider from an invitation link consumes the invitation, provided the provider e-mail matches the invited one — and creates the account even with allowAccountCreation off, since the invitation is itself the permission to join.

htmlRender — HTML & email rendering

The backend renders HTML templates (transactional emails, static HTML) by calling the frontend's render endpoint with a short-lived service token — see Backend services.

realtime — transport driver

The realtime layer (SSE topics, presence, notification streams — see Backend services) picks its broker with realtime.driver:

nuxt — layer distribution

The backend serves the frontend's Nuxt layers over two routes that acms consumes: GET /cms/nuxt (the manifest) and GET /cms/modules (a ZIP of every registered layer's source). They carry things no browser and no stranger should see — each layer's privateOptions (oauth.relaySecret, htmlRender.serviceSecret), and the full source of every layer any module registered with AddNuxtLayer, including its Nitro server/ routes.

bootstrapSecret is the credential acms presents to reach them.

config: {
  nuxt: {
    bootstrapSecret: process.env.CMS_BOOTSTRAP_SECRET,
  },
},

Set the same value as CMS_BOOTSTRAP_SECRET in the environment that runs acms build. It is deliberately not derived from auth.jwtSecret: it lives on a build host, so it must not be a function of the secret that signs session tokens, and rotating it must not log every user out.

In development nothing needs configuring: the instance generates an ephemeral per-boot credential and publishes it to the project's .antelope/cms-dev.json (owner-readable only, stamped with its pid), where acms dev and acms prepare find it by walking up from the working directory. The file outlives the instance that wrote it — deleting it on shutdown could race a replacement backend's freshly published credential — but a leftover copy is ignored once its pid is gone.