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 group | Purpose | Resource name |
|---|---|---|
| Identity providers | Define sign-in providers needed by the instance | identity-providers/{idp} |
| Instance settings | Define instance-wide access, policy, storage, notification, AI, memo, and usage rules | instance/settings/{setting} |
| Users | Bootstrap and maintain selected administrator or user identity fields | users/{user} |
| Linked identities | Define which identity-provider subject signs in as a declared user | users/{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:
- Schema validation checks resource names, matching instance-setting value groups, user identity fields, lifecycle references, removed entries, and valid ignored field paths.
- 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.
- 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.
| Action | Meaning |
|---|---|
CREATE | The declaration has no matching stored resource |
ADOPT | An existing stored resource becomes managed and is brought to the declaration |
UPDATE | A managed resource differs from its declaration |
NO_OP | The managed resource already matches |
DESTROY | An explicitly removed identity provider is deleted |
RESET | An explicitly removed instance-setting group returns to its defaults |
RELEASE | Management ends and the stored resource stays unchanged |
ERROR | A 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:
- Read the configuration state and actual resources inside the transaction.
- Compute the plan that the command or startup path will report.
- Apply the ordered resource operations through transaction-scoped store writes.
- Add apply metadata and write the next configuration state with the next serial.
- 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,
removedhandling, 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, andwriteOnlyVersionaffect 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
| Trigger | Consequence | Guard |
|---|---|---|
A managed resource is removed from files without a removed entry | The plan is invalid and apply writes nothing | Add an explicit release or destroy declaration |
| The last identity provider is removed while password sign-in stays disabled | The plan fails before any write | Keep an identity provider or enable password sign-in in the planned state |
A removed entry requests destruction while preventDestroy is recorded | The plan refuses the destroy | Apply once without destroy protection, then remove the resource |
| A configuration tries to delete a managed user | The plan fails because configuration never deletes users | Release the user and delete it through Settings |
| An API update changes a managed field | The API returns FAILED_PRECONDITION and the resource source | Edit the configuration file and apply, or release that field with ignoreChanges |
| A usage-limit declaration names a user that does not exist | Planning fails because the stored reference cannot be resolved | Create the user first or remove the reference |
| Two files declare the same resource or lifecycle rule | Loading fails before planning | Keep one declaration for each stable resource name |
| A configured secret is printed through plan or state output | Sensitive data can leak to operators or logs | Use the masked plan and state paths and keep secrets in references or protected files |
| Two replicas apply different configuration generations during a rollout | The last startup apply can replace the earlier generation | Apply once through a deployment job or roll out identical files |
Key files
| File | Why to read it |
|---|---|
| home/…/configuration.proto | Defines the public configuration, lifecycle, removal, plan, linked-identity, and resource-change contract. |
| home/…/configuration.go | Shows how configuration files become one desired state. |
| home/…/decode.go | Explains substitution and strict decoding behavior. |
| home/…/schema.go | Defines resource identity and document-level validation. |
| home/…/plan.go | Defines comparison, drift, removal, ordering, and end-state checks. |
| home/…/apply.go | Shows atomic application and resource write behavior. |
| home/…/configuration_state.go | Defines persisted ownership state and transaction coordination for resource writes. |
| home/…/guard.go | Defines the shared rules for rejecting conflicting API writes. |
| home/…/instance_service_configuration.go | Exposes status and translates ownership refusals into API errors. |
| home/…/config.go | Defines the CLI workflows for validation, planning, applying, and reading state. |
| home/…/main.go | Shows when startup applies configuration and how config-apply=off changes the rollout model. |
| home/…/useConfigurationQueries.ts | Maps status resources and field paths to client-side ownership state. |
| home/…/ConfigurationSection.tsx | Shows how administrators view managed resources and last-apply metadata. |