Services

A config has one stanza per service, plus authorization and security, which configure GenoaCMS itself. Every stanza except deployment is required. The example configs show each of them filled in.

Authentication

Checks that users are who they claim to be. GenoaCMS keeps the session itself, as signed tokens in one cookie; see identity and sessions .

authentication: {
  providers: Record<string, AuthenticationProvider>
  cookieName: string
}

At sign-in the providers are tried one at a time, in key order, until one recognizes the user. Several providers can therefore serve one instance — an identity platform for editors and a fixed list for a break-glass administrator, for example.

authentication: {
    cookieName: '__session'
}

Database

The databases GenoaCMS edits, and the collections in each.

database: {
  providers: Record<string, DatabaseProvider>
  databases: Record<string, { provider: string, collections: CollectionReference[] }>
}

Each database names its provider by key. Collections describe data that already exists in your database, so GenoaCMS can edit it in place: genoa init puts them in genoa.config/collections.ts, which every config imports.

import type { CollectionReference } from '@genoacms/contracts/database'
import { storageResource } from '@genoacms/contracts/schemas'

export const collections: CollectionReference[] = [
  {
    name: 'authors',
    primaryKey: { key: 'id', schema: { type: 'string' } },
    schema: {
      type: 'object',
      properties: {
        id: { type: 'string', format: 'uuid' },
        name: { type: 'string' },
        photo: storageResource
      }
    }
  }
]

• name is the collection's or table's name in the database.
• primaryKey.key is the field that identifies a document, and primaryKey.schema its type. The AWS adapter accepts only string keys.
• schema is a JSON Schema object describing a document; the contract types it as JsonSchema.
• uiSchema, optional, tells the CMS how to show each field, keyed by field name: { body: { showPreview: false } } leaves body out of the collection listing.

@genoacms/contracts/schemas adds fields that point outside the document: storageResource and nullableStorageResource for an object in a bucket, and reference({ collection }) for a document of another collection.

Storage

The buckets GenoaCMS reads and writes, one of which holds its own data.

storage: {
  providers: Record<string, StorageProvider>
  buckets: Record<string, { provider: string }>
  defaultBucket: string
  pathDelimiter?: string   // default '|->'
}

Each key of buckets is the name of a bucket that already exists, bound to the provider that serves it. defaultBucket names the bucket where GenoaCMS keeps its own data under .genoacms/ — see what GenoaCMS stores . pathDelimiter separates path segments in the storage browser's URLs.

Secrets

Holds what must live neither in the bucket nor in the config: GenoaCMS's signing seeds, and every credential a config refers to with secret().

secrets: {
  providers: Record<string, SecretsProvider>   // exactly one
}

What GenoaCMS stores here

GenoaCMS creates all of these itself. Nothing here has to be set by hand.

The root signing key

On first start GenoaCMS generates a root trust anchor — the key at the top of its signing chain — and stores its seed as GENOACMS_ROOT_KEY_SEED. A line naming the new key's id is written to the log when this happens:

[genoacms:signing] generated a new root trust anchor, keyId 9f2c41ab8d7e0355.

Only the seed is stored; the keypair is derived from it at startup. That keeps one short value in the secret manager rather than a multi-kilobyte key, and holding the seed is equivalent to holding the key, so nothing is given away by storing the smaller thing.

To provision the key yourself instead of letting it be generated — for a multi-region deployment, or to keep the anchor under existing key management — write the seed to the secret store before first start. GenoaCMS generates one only when none is present.

Languages

The languages components may be authored in, keyed by the language a component records.

languages: {
  providers: Record<string, LanguageProvider>
}

languages: {
  providers: {
    typescript: languageProvider('@genoacms/language-adapter-ts', { target: 'es2020' })
  }
}

A component records its language, and GenoaCMS resolves the adapter from it, so several languages can coexist. See adding a language .

Deployment

Where genoa build and genoa deploy send GenoaCMS.

deployment?: {
  targets: Record<string, DeploymentTarget>
  default?: string
}

A target is an adapter that knows how to build for and publish to one platform. genoa deploy gcp picks the target by key; without one it takes default, else the first key. A config used only by genoa dev may leave the stanza out; a build requires it.

A target's options — credentials included — are read only on the machine running genoa deploy. They never enter the build.

Authorization and security

Neither is a service: they configure GenoaCMS itself.

authorization: {
  roles?: Record<string, Grant[]>
  assignments?: Record<string, string[]>
  lockRoles?: boolean
}

security: {
  accessTokenMinutes?: number           // default 15
  refreshTokenDays?: number             // default 14
  grantCacheSeconds?: number            // default 30
  subordinateKeyRotationDays?: number   // default 90
  maxFuel?: number                      // default 1 000 000
  maxDepth?: number                     // default 100
  maxAllocation?: number                // default 10 000 000
  fetchOrigins?: string[]               // default [], which permits nothing
}

maxFuel, maxDepth and maxAllocation are the ceilings a dynamic component runs under: loop iterations and recursive branches per render, call depth, and elements and bytes allocated per render. They are compiled into each published component and covered by its signature, so a consumer may run below them but never above. fetchOrigins lists the origins — scheme, host and optional port — a dynamic component's data bridge may reach.

Two stanzas rather than one, because they behave oppositely: everything in authorization is authority, re-read on every resolution, while everything in security is a seed consumed once at first start.

roles declares roles by name; assignments maps a subject to the roles it holds. A subject is the provider-issued identifier from the authentication service, never an email address.

A new instance needs at least one assignment, or nobody can administer it:

authorization: {
  roles: {
    Administrator: [{ permission: '*', resource: '*' }]
  },
  assignments: {
    'the-subject-of-your-first-administrator': ['Administrator']
  }
}

Runtime administration remains free to create roles and assignments that genoa.config does not name. Set authorization.lockRoles to true to disable runtime administration entirely, for an instance whose authorization should be fixed at deployment — it sits beside the declarations because it governs exactly them.

security.subordinateKeyRotationDays sets how long a signing key stays current — see key rotation .

When a config does not load

The loader reports every problem at once, each with the path of the offending field, under config/invalid. Each problem has one of these codes:

At build time, config/unknown-target means the target named on the command line is not a key of deployment.targets, and config/no-deployment-target that a target was requested from a config that declares none.