Configure Chronicle
Most Chronicle problems that look like bugs are a setting: a message size that
differs between client and kernel, a development default left in a deployed
environment, a port or TLS switch that does not match the other side. Find the
setting, its default and the side that owns it before changing code.
Two surfaces exist and they are configured differently:
| Surface |
Where it lives |
How to set it |
Client (ChronicleOptions) |
The application |
Code, Cratis:Chronicle configuration section, or the connection string |
| Kernel (server options) |
The cratis/chronicle container or process |
chronicle.json mounted at /app/chronicle.json, or Cratis__Chronicle__* environment variables |
A setting on one side never changes the other. Where both sides enforce a limit
(gRPC message size), change both.
Workflow
- Name the symptom and the side. Read symptoms first;
it maps error text to the setting that usually causes it.
- Look up the setting: client options or
kernel options. Both list the default and when
changing it is justified.
- For a container or CI deployment, translate the JSON path to an environment
variable with environment variables.
- For a local developer machine, follow the
development inner loop instead of
copying production settings.
- Change one setting, restart the side that owns it, and reproduce the symptom.
Rules that prevent the common mistakes
- Do not state a default from memory. Read the reference; if a setting is
not listed, read the product options type or documentation before answering.
DEVELOPMENT is a compile-time symbol of the image, not an environment
variable. latest-development images behave as development kernels;
ASPNETCORE_ENVIRONMENT does not turn a production image into one. The
runtime environment (Development) separately controls webhook and capture
AllowInsecureHttp and the loopback exemption. The Validation default
(Warn versus BlockLocalAddresses) follows the image, not the runtime
environment.
- Certificate validation is skipped by default on the client. That suits the
self-signed development image. A deployed client must opt in to validation.
Authentication:Authority is an external identity provider's issuer URL.
A non-empty value disables the built-in issuer. It is never the kernel's own
URL.
- Secrets go in
*File variants or secret management, not in committed
chronicle.json, images or logs. Do not quote or invent credential values.
- Caller-set namespace resolvers are not trusted on their own. The default
HTTP header resolver (
NamespaceHttpHeader) and the subdomain resolver both
read values the caller sets. Strip or overwrite the header at a trusted
gateway, or resolve from an authenticated claim, before it selects a tenant.
- A settings change is not authorization to restart, redeploy or alter a shared
environment. State the change and its blast radius first.
References
- Read client options for
ChronicleOptions,
ASP.NET Core options and the connection-string switches.
- Read kernel options for ports, TLS, features,
observers, authentication, clustering and storage keys.
- Read environment variables for the
naming rule, list indexes and secret
*File variants.
- Read development inner loop for the
development image, port, credentials, first Workbench sign-in and TLS switches.
- Read symptoms when starting from an error or odd
behavior rather than a setting.
Related skills
- Use
cratis-chronicle-hosting for production topology, certificates,
MongoDB replica sets, clustering and backup order; this skill does not repeat
them.
- Use
cratis-chronicle-client-dotnet for client wiring and lifecycle;
its connection-options reference holds connection-string forms.
- Use
cratis-chronicle-multi-tenancy for namespace resolution design.
- Use
cratis-arc-configuration for Arc's own settings.
1---2name: cratis-chronicle-configuration3description: Use when choosing, changing or diagnosing Chronicle client or kernel settings, defaults, environment variables or the local development loop. Not for production topology (use cratis-chronicle-hosting) or client wiring (use the client skills).4license: MIT5metadata:6 source: https://skillmd.com/skills/cratis/cratis-chronicle-configuration7---89<!-- Copyright (c) Cratis. All rights reserved. -->10<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->1112# Configure Chronicle1314Most Chronicle problems that look like bugs are a setting: a message size that15differs between client and kernel, a development default left in a deployed16environment, a port or TLS switch that does not match the other side. Find the17setting, its default and the side that owns it before changing code.1819Two surfaces exist and they are configured differently:2021| Surface | Where it lives | How to set it |22| --- | --- | --- |23| Client (`ChronicleOptions`) | The application | Code, `Cratis:Chronicle` configuration section, or the connection string |24| Kernel (server options) | The `cratis/chronicle` container or process | `chronicle.json` mounted at `/app/chronicle.json`, or `Cratis__Chronicle__*` environment variables |2526A setting on one side never changes the other. Where both sides enforce a limit27(gRPC message size), change both.2829## Workflow30311. Name the symptom and the side. Read [symptoms](references/symptoms.md) first;32 it maps error text to the setting that usually causes it.332. Look up the setting: [client options](references/client-options.md) or34 [kernel options](references/kernel-options.md). Both list the default and when35 changing it is justified.363. For a container or CI deployment, translate the JSON path to an environment37 variable with [environment variables](references/environment-variables.md).384. For a local developer machine, follow the39 [development inner loop](references/development-inner-loop.md) instead of40 copying production settings.415. Change one setting, restart the side that owns it, and reproduce the symptom.4243## Rules that prevent the common mistakes4445- **Do not state a default from memory.** Read the reference; if a setting is46 not listed, read the product options type or documentation before answering.47- **`DEVELOPMENT` is a compile-time symbol of the image**, not an environment48 variable. `latest-development` images behave as development kernels;49 `ASPNETCORE_ENVIRONMENT` does not turn a production image into one. The50 runtime environment (`Development`) separately controls webhook and capture51 `AllowInsecureHttp` and the loopback exemption. The `Validation` default52 (`Warn` versus `BlockLocalAddresses`) follows the image, not the runtime53 environment.54- **Certificate validation is skipped by default on the client.** That suits the55 self-signed development image. A deployed client must opt in to validation.56- **`Authentication:Authority` is an external identity provider's issuer URL.**57 A non-empty value disables the built-in issuer. It is never the kernel's own58 URL.59- **Secrets go in `*File` variants or secret management**, not in committed60 `chronicle.json`, images or logs. Do not quote or invent credential values.61- **Caller-set namespace resolvers are not trusted on their own.** The default62 HTTP header resolver (`NamespaceHttpHeader`) and the subdomain resolver both63 read values the caller sets. Strip or overwrite the header at a trusted64 gateway, or resolve from an authenticated claim, before it selects a tenant.65- A settings change is not authorization to restart, redeploy or alter a shared66 environment. State the change and its blast radius first.6768## References6970- Read [client options](references/client-options.md) for `ChronicleOptions`,71 ASP.NET Core options and the connection-string switches.72- Read [kernel options](references/kernel-options.md) for ports, TLS, features,73 observers, authentication, clustering and storage keys.74- Read [environment variables](references/environment-variables.md) for the75 naming rule, list indexes and secret `*File` variants.76- Read [development inner loop](references/development-inner-loop.md) for the77 development image, port, credentials, first Workbench sign-in and TLS switches.78- Read [symptoms](references/symptoms.md) when starting from an error or odd79 behavior rather than a setting.8081## Related skills8283- Use `cratis-chronicle-hosting` for production topology, certificates,84 MongoDB replica sets, clustering and backup order; this skill does not repeat85 them.86- Use `cratis-chronicle-client-dotnet` for client wiring and lifecycle;87 its connection-options reference holds connection-string forms.88- Use `cratis-chronicle-multi-tenancy` for namespace resolution design.89- Use `cratis-arc-configuration` for Arc's own settings.