Skip to content

Development And Production Images

Chronicle ships a development image and a production image. They are not the same binary with a different environment name. The development image is built with the compile-time DEVELOPMENT symbol and carries its own chronicle.json and appsettings.json; the production image is built without the symbol and ships neither file’s development values. Read this page before you move from latest-development to latest, or when behavior verified on the development image differs in production.

The DEVELOPMENT symbol, not the environment name

Section titled “The DEVELOPMENT symbol, not the environment name”

The behaviors in the table below are decided when the kernel is compiled. ASPNETCORE_ENVIRONMENT and DOTNET_ENVIRONMENT do not turn them on or off, so setting ASPNETCORE_ENVIRONMENT=Production on the development image does not make it behave like the production image, and setting Development on the production image does not enable them. The runtime environment does control the webhook and external-service exceptions described below, so never run a production deployment with the Development environment.

Behavior Development image (DEVELOPMENT defined) Production image
TLS certificate for the main port Generates a self-signed certificate when TLS is enabled and none is configured Fails at startup with “No TLS certificate is configured”. Configure Tls:CertificatePath
Encryption certificate (Data Protection key protection, webhook secrets) Loads or generates a development certificate under certificates/ in the working directory when none is configured Throws EncryptionCertificateNotConfigured on first use
OAuth authority signing and encryption keys Uses ephemeral keys when no encryption certificate is configured, so tokens stop validating after a restart Fails at startup with “An encryption certificate is required in production”
Authentication:DefaultAdminPassword Honored: the administrator is created with that password and the first-password setup flow is skipped The property does not exist in the build, so the key is ignored without an error. Use Authentication:AdminUser instead
Webhooks:Validation and ExternalServices:Validation default Warn BlockLocalAddresses
Development-only operations such as resetting kernel state Available Not compiled in; the calls throw

Because the production image ignores DefaultAdminPassword silently, a configuration that works in the development image can leave the production kernel without the administrator password you expected. Set Authentication:AdminUser (username and password) for every environment, and see Authentication for the first-login flow.

Webhooks:Validation and ExternalServices:Validation choose how Chronicle treats a destination that resolves to a local or private address. The code default is BlockLocalAddresses in production builds and Warn in development builds, so by default a webhook that targets localhost delivers on the development image and is blocked on the production image.

Two exceptions depend on the runtime environment, not on the image: AllowInsecureHttp, and the exemption that lets loopback and host.docker.internal destinations skip the AllowedHosts and address checks. Both apply only when the kernel runs with the Development environment, and they apply on either image. A production image started with ASPNETCORE_ENVIRONMENT=Development therefore accepts plain-HTTP and loopback destinations; run production with the Production environment. To reach an internal destination in production, add it to AllowedHosts (or EventStoreAllowedHosts per event store) instead of weakening validation. See Webhooks and External services.

The development image ships two configuration files that change defaults. The production image removes chronicle.json and appsettings.Development.json, so none of these values apply there.

Setting Code default (production) Development image Source
observers.subscriberTimeout 30 seconds 5 seconds Source/Kernel/Server/chronicle.json
observers.replayOnDefinitionChange false true Docker/Development/appsettings.json
observers.definitionEvolution Automatic Automatic (set explicitly, same as the code default) Docker/Development/appsettings.json
storage Empty connection details; there is no built-in fallback MongoDB at mongodb://localhost:27017 (the bundled MongoDB) Source/Kernel/Server/chronicle.json
authentication.defaultAdminPassword Not available Set to a well-known development value Source/Kernel/Server/chronicle.json

Two of these change behavior you can observe in a test:

  • A subscriber that takes longer than 5 seconds is reported as timed out on the development image but would have succeeded within the 30-second default. Raise it to the production value when you want the development image to match. See Observers.
  • With replayOnDefinitionChange on, a detected change to a reactor or webhook definition (for a reactor, the event types it subscribes to) replays it automatically in development. It does not detect changes to handler code or event type schemas. In production the flag is off, so plan the replay explicitly. Projection and reducer definition changes are governed by observers.definitionEvolution, which is Automatic on both images. See Observers.

To make the development image behave like production for these two settings, set them in your Compose file:

environment:
Cratis__Chronicle__Observers__SubscriberTimeout: "30"
Cratis__Chronicle__Observers__ReplayOnDefinitionChange: "false"
  1. Configure storage; the production image has no bundled database.
  2. Configure the TLS certificate and the encryption certificate.
  3. Set Authentication:AdminUser instead of DefaultAdminPassword.
  4. Review Webhooks:Validation, ExternalServices:Validation and the allowed hosts for destinations that are local in development.
  5. Set observers.subscriberTimeout and observers.replayOnDefinitionChange to the values you want, since the development values no longer apply.

See Production hosting for the full checklist.