Introducing a new way to review your PRs.

Read the announcement

usememos / memos

Memos is an open-source, self-hosted note-taking app that brings your everyday thoughts together in a personal timeline. Your data stays yours, and you choose what to keep private or share.

View on GitHub

25 documents · Updated Nov 20, 2026

docs / declarative-configuration-management

Declarative configuration management

Declarative configuration management lets an operator describe instance resources in versioned JSON files and bring the database to that desired state. Memos validates the files, plans the difference, applies the plan as one guarded transaction, and stores ownership state so API clients and later applies use the same resource contract. See deployment, configuration, and operations for the wider process and deployment lifecycle. See API contracts and services for the wider service interface and persistence and data evolution for database state and migration context.

Desired state

The desired state is the merged configuration from the JSON files in the configured directory. Each resource uses the public API schema and a stable resource name, so the same declaration can address the same instance resource across deployments.

Configuration resources

The schema manages four resource groups. Instance settings are complete groups rather than patches. User declarations manage only the fields they include for optional profile fields, while linked identities connect a declared user to an identity-provider subject.

Resource groupPurposeResource name
Identity providersDefine sign-in providers needed by the instanceidentity-providers/{idp}
Instance settingsDefine instance-wide access, policy, storage, notification, AI, memo, and usage rulesinstance/settings/{setting}
UsersBootstrap and maintain selected administrator or user identity fieldsusers/{user}
Linked identitiesDefine which identity-provider subject signs in as a declared userusers/{user}/linkedIdentities/{linked_identity}

The configuration also has two control lists. lifecycle can ignore field paths, prevent destruction, or request another write of a write-only user password. removed makes the end of management explicit and chooses release or destruction. (home/…/configuration.proto• L12-65, home/…/schema.go• L18-67)

File loading

Memos reads regular *.json files from one directory and merges them into one desired state. A resource name can appear in only one file, while the source file is retained for plans, state, and API error messages. Environment and absolute file references provide a way to supply secret values without placing them in the main document.

The loader treats a missing directory as an empty desired state. It ignores other file types and nested entries. It decodes each document strictly, accepts enum names rather than numbers, rejects output-only fields, and reports deprecated fields as warnings. It also keeps substituted values out of error text. (home/…/configuration.go• L33-45, home/…/configuration.go• L72-128, home/…/decode.go• L33-61, home/…/decode.go• L157-193)

Validation

Validation prevents an invalid desired state from reaching planning or application. It starts with file and schema checks, then applies the same resource rules used by the API so a configuration file and an API write follow one validity contract.

Validation layers

The validation path has three levels:

  1. Schema validation checks resource names, matching instance-setting value groups, user identity fields, lifecycle references, removed entries, and valid ignored field paths.
  2. Resource validation checks the complete identity-provider, instance-setting, user, or linked-identity value as it will be stored. This includes provider-specific settings, storage completeness, email rules, and normalized values.
  3. Cross-resource validation runs during planning when the database is available. It resolves resource references such as users named by usage limits and checks that the planned end state keeps a valid authentication path.

The standalone memos config validate command runs without a database. memos config plan adds actual-state checks and produces the full plan. (home/…/schema.go• L69-165, home/…/resources.go• L15-46, home/…/plan.go• L112-118, home/…/config.go• L36-43, home/…/config.go• L160-174)

Planning

Planning compares desired state with actual database resources and the persisted ownership state. It never writes. Its result explains the action for each declared or previously managed resource and shows whether a difference comes from the file or from drift outside the configuration.

Resource actions

The plan uses stable resource names and produces deterministic output. A declared resource that already exists but is not managed is adopted. A managed resource that differs is updated. A managed resource that is no longer declared requires an explicit removed entry rather than an implicit destroy.

ActionMeaning
CREATEThe declaration has no matching stored resource
ADOPTAn existing stored resource becomes managed and is brought to the declaration
UPDATEA managed resource differs from its declaration
NO_OPThe managed resource already matches
DESTROYAn explicitly removed identity provider is deleted
RESETAn explicitly removed instance-setting group returns to its defaults
RELEASEManagement ends and the stored resource stays unchanged
ERRORA managed resource disappeared from the files without a removed entry, or a guarded removal is unsafe

Plans show field paths and old and new values for updates and adoption. Sensitive values are masked. Passwords are write-only and are sent only on creation or when the user lifecycle version increases. A plan marks drift when the stored value changed after the last applied declaration. (home/…/configuration.proto• L68-143, home/…/plan.go• L146-180, home/…/plan.go• L452-509, home/…/diff.go• L22-64)

Apply ordering

The plan orders operations so the planned intermediate state remains usable. Identity-provider creates and updates come first. Instance settings follow. User and linked-identity operations come next, and identity-provider destruction comes last so users are removed before their sign-in provider is removed. Resource names sort within each group. (home/…/plan.go• L68-76, home/…/plan.go• L535-564)

The planner also checks the authentication invariant against the final state. If password sign-in is disabled and no identity provider would remain, a plan that changes that condition is rejected before apply. (home/…/plan.go• L511-531)

Guarded application

Application recomputes the plan from database state inside one serializable transaction and writes resources and ownership state together. A valid apply either completes as one unit or changes nothing, so a failed resource write cannot leave a partial configuration.

Apply transaction

The application flow is:

  1. Read the configuration state and actual resources inside the transaction.
  2. Compute the plan that the command or startup path will report.
  3. Apply the ordered resource operations through transaction-scoped store writes.
  4. Add apply metadata and write the next configuration state with the next serial.
  5. Commit, then clear affected caches and revoke user sessions when a configured password changed.

An empty plan does not write the database or advance the serial. Concurrent applies use serializable isolation and a conditional state write. A conflict retries from fresh transaction state so identical replicas converge on one committed result. (home/…/apply.go• L20-74, home/…/configuration_state.go• L232-295)

Apply entry points

The CLI provides separate validation, planning, application, and state views. The apply command migrates the database before it runs and prints the plan it actually applied. A detailed plan exit code lets automation distinguish no changes from changes.

flowchart TD
    Files[Configuration files] --> Validate[Load and validate]
    Validate --> Plan[Compute plan against database]
    Plan --> Review[Print text or JSON plan]
    Review --> Apply[memos config apply or startup apply]
    Apply --> Tx[Apply resources and state in one transaction]
    Tx --> State[Persist serial and managed resources]
    State --> Guard[API ownership checks]

Server startup can apply the same configuration after migration and before services start. config-apply=off leaves application to an external job, but the running replicas still read the persisted state for API ownership checks. (home/…/config.go• L33-89, home/…/config.go• L208-245, home/…/main.go• L250-284)

Persistence state

The configuration state is a database record of management, not a second copy of configured values. It links resource names to their source and ownership rules, records the last apply, and lets every replica enforce the same ownership without reading the configuration directory.

State record

Memos stores the state as the CONFIGURATION_STATE value in the instance-setting store. Before the first changed apply, the record is empty with serial zero. A changed apply increases the serial and records the configuration digest, apply time, apply path and host, Memos version, and managed resources.

Each managed resource records its kind, source file, managed and ignored fields, last applied digest, write-only version, destroy protection, and named resource references. These fields support drift detection, explicit removal, password resend control, and API checks without storing configured secrets. (home/…/configuration_state.go• L15-31, home/…/instance_setting.proto• L277-323)

State visibility

The CLI memos config state shows the serial, last apply, and managed resource ownership. The admin-only GetConfigurationStatus RPC returns the same operational view through the API: resource names, source files, managed fields, ignored fields, digest, version, and apply time. It does not return configured values. (home/…/config.go• L286-319, home/…/instance_service.proto• L572-610, home/…/instance_service_configuration.go• L23-55)

API ownership

The API treats the persisted state as the ownership authority. A replica can refuse a conflicting write even when it did not load the files, because the guard reads the state record for each protected mutation.

Mutation guard

The guard rejects a write when it would change a managed field, create or delete a managed resource, or rename or delete a resource named by a managed declaration. It returns FAILED_PRECONDITION with MANAGED_BY_CONFIGURATION and identifies the resource, source file, affected fields, and any referring resource.

Ignored fields and write-only password fields remain editable through the API. A write that resends managed values without changing them is also allowed. The API guard is an enforcement layer; the web controls only explain the ownership and reduce avoidable rejected writes. (home/…/guard.go• L13-74, home/…/instance_service_configuration.go• L58-119, home/…/instance_service.proto• L40-48)

Client presentation

The web client reads configuration status for administrators and uses resource names and field paths to mark managed controls. It shows the source file and last apply summary in the Configuration settings section. It keeps ignored paths and undeclared user profile fields editable, while the server remains the final authority. (home/…/useConfigurationQueries.ts• L11-47, home/…/ConfigurationSection.tsx• L13-67, home/…/ManagedByConfigurationChip.tsx• L9-21)

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the public API resource schema, strict file decoder, compatibility fixtures, and API-to-store validation rules aligned.
  • When adding a resource field, decide whether it is managed, sensitive, output-only, or write-only in the schema, plan display, digest, state record, and API guard.
  • Keep resource-name parsing, state keys, plan actions, removed handling, and API ownership checks aligned when a resource kind or identity format changes.
  • Keep linked-identity declarations aligned with declared users, provider subjects, removal rules, transaction writes, and ownership checks.
  • When changing lifecycle fields, preserve how ignoreChanges, preventDestroy, and writeOnlyVersion affect plans, state, and guarded API writes.
  • When changing usage-limit references or other cross-resource links, update planning resolution, state references, and rename or delete guards together.
  • When changing apply order or transaction behavior, preserve the final authentication invariant and the atomic resource-plus-state write.
  • Keep CLI output and exit codes, startup apply mode, state status RPC fields, and web ownership presentation aligned.
  • Keep sensitive and write-only values out of plans, logs, state, status responses, and error messages.

Important failure modes

TriggerConsequenceGuard
A managed resource is removed from files without a removed entryThe plan is invalid and apply writes nothingAdd an explicit release or destroy declaration
The last identity provider is removed while password sign-in stays disabledThe plan fails before any writeKeep an identity provider or enable password sign-in in the planned state
A removed entry requests destruction while preventDestroy is recordedThe plan refuses the destroyApply once without destroy protection, then remove the resource
A configuration tries to delete a managed userThe plan fails because configuration never deletes usersRelease the user and delete it through Settings
An API update changes a managed fieldThe API returns FAILED_PRECONDITION and the resource sourceEdit the configuration file and apply, or release that field with ignoreChanges
A usage-limit declaration names a user that does not existPlanning fails because the stored reference cannot be resolvedCreate the user first or remove the reference
Two files declare the same resource or lifecycle ruleLoading fails before planningKeep one declaration for each stable resource name
A configured secret is printed through plan or state outputSensitive data can leak to operators or logsUse the masked plan and state paths and keep secrets in references or protected files
Two replicas apply different configuration generations during a rolloutThe last startup apply can replace the earlier generationApply once through a deployment job or roll out identical files

Key files

FileWhy to read it
home/…/configuration.protoDefines the public configuration, lifecycle, removal, plan, linked-identity, and resource-change contract.
home/…/configuration.goShows how configuration files become one desired state.
home/…/decode.goExplains substitution and strict decoding behavior.
home/…/schema.goDefines resource identity and document-level validation.
home/…/plan.goDefines comparison, drift, removal, ordering, and end-state checks.
home/…/apply.goShows atomic application and resource write behavior.
home/…/configuration_state.goDefines persisted ownership state and transaction coordination for resource writes.
home/…/guard.goDefines the shared rules for rejecting conflicting API writes.
home/…/instance_service_configuration.goExposes status and translates ownership refusals into API errors.
home/…/config.goDefines the CLI workflows for validation, planning, applying, and reading state.
home/…/main.goShows when startup applies configuration and how config-apply=off changes the rollout model.
home/…/useConfigurationQueries.tsMaps status resources and field paths to client-side ownership state.
home/…/ConfigurationSection.tsxShows how administrators view managed resources and last-apply metadata.