Configuration reference

Applications and integrated modules define configuration together. This page indexes common default-template fields; inspect an installed application's complete metadata with pnpm nocobase config variables --json. For the development workflow, see Application configuration (config.yml).

Files and precedence

The default template merges values in this order, with later values taking precedence:

Code defaults in server/config/
    → config.yml
    → explicitly mapped environment variables

Plain objects merge recursively; arrays and scalars are replaced. Environment variables require declared mappings and are not arbitrarily converted into paths. ${NAME} in YAML is a literal string, not automatic interpolation.

Run pnpm nocobase config init --dialect sqlite in an uninitialized app to generate local configuration and keys from the example. Preserve existing keys when upgrading; reinitialization is not an upgrade procedure.

Common configuration fields

This is an index of configuration locations, not a complete file to copy. Consult the current template and package declarations for defaults, supported fields and plugin sections.

For example, merge these values into an initialized local development app's existing configuration:

server:
  host: 127.0.0.1
  port: 13000

client:
  app:
    title: My App
    defaultColorScheme: system

Preserve its database and key configuration. To allow LAN access, bind to 0.0.0.0 as appropriate and use the machine's actual IP in the browser; 0.0.0.0 is not the browser address. Development may use a separate frontend port; follow the URL printed by pnpm dev.

Database configuration

Connections live at database.connections.<name>; database.default selects the default. SQLite uses filename. Other dialects commonly use host, port, database, username and password; see Database support and version compatibility for dialect-specific fields.

schemaManagement: managed allows framework schema management. external restricts framework schema changes for an external database; it does not make business data automatically read-only. Account permissions and authorization policies still apply.

SQLite also accepts the template’s database filename spelling, which takes precedence when both it and filename are present. Use one spelling consistently when changing file locations, so an old database value does not override DB_FILENAME.

Default DB_* mappings target only main. Declare mappings for additional connections with connectionEnvironment(name, prefix) from @nocobase/app-server/database, retaining the default connection mappings. Changing a dialect or address does not migrate existing data.

Environment variables

The following mappings come from the checked application's metadata. Authentication, mail and notification mappings depend on their modules; consult current command output for exact types, descriptions and sensitive-field markers.

Three additional variables are read by the runtime:

SECRETS_KEYS contains comma-separated version:key entries, with the current key first. Keep entries still needed to decrypt older data and follow the rotation process. Key changes can also invalidate existing sessions. Each module chooses explicit or derived keys according to its own rules. For example, sessions prefer an explicit session.secret and try Secrets derivation when it is absent. Check the module’s configuration contract and key-rotation requirements before changing these values.

Browser-visible configuration

The client section is embedded in application pages and readable by browsers. Other server sections expose only leaf paths explicitly listed in defineAppConfig()'s public option. Keep database passwords, signing keys and mail credentials out of client and public paths.

For an announcements section, add server/config/announcements.ts:

import { defineAppConfig, envInteger } from '@nocobase/app-server/config';

export default defineAppConfig({
  defaults: { pageSize: 20 },
  env: {
    ANNOUNCEMENTS_PAGE_SIZE: envInteger('pageSize', {
      description: 'Default number of announcements per page.',
    }),
  },
  public: ['pageSize'],
  validate(value, context) {
    if (!Number.isInteger(value.pageSize) || value.pageSize < 1 || value.pageSize > 100) {
      context.error('pageSize', 'Expected an integer between 1 and 100.');
    }
  },
});

Import and add announcements to the existing defaultAppConfigs({ ... }) in server/config/index.ts, and update its explicitly listed return type. Its file key is announcements.pageSize, with environment override ANNOUNCEMENTS_PAGE_SIZE. public: ['pageSize'] publishes only that field.

Validators run at startup, reload and config check. Validate actual values and avoid network requests or writes. Reloading configuration does not guarantee that existing services automatically adopt new behavior; services must handle updates themselves.

Editing and checking

pnpm nocobase config set server.port=13000
pnpm nocobase config env
pnpm nocobase config variables --json
pnpm nocobase config check --no-connect

Read a sensitive value from an existing environment variable into local configuration:

pnpm nocobase config set --from-env database.connections.main.password=MAIN_DB_PASSWORD

Set MAIN_DB_PASSWORD through your environment-management mechanism first. This writes its current value, not a dynamic variable reference. If DB_PASSWORD is also set, it overrides the file value.

config check normally validates configuration and attempts non-SQLite connections. Use --no-connect offline and --strict to treat warnings as failures. When reporting a problem, supply field names, redacted errors and package versions rather than an entire configuration file. See the Command-line reference.

Verification scope

Definitions were checked against Core 015404ecd0db configuration sources. Variable metadata and offline checks used default template beta.83, @nocobase/app-cli 1.0.0-beta.29 and @nocobase/config 0.1.0-beta.3. Additional plugins may introduce more sections and mappings.