Production readiness

Production readiness is not one switch. Cratis gives you the event log, generated contracts, operational tools, and hosting configuration, but you still need explicit choices for storage, secrets, identity, deployment, monitoring, replay, and incident handling.

Use this checklist before deploying Chronicle or a full Cratis application. Each item links to the product page that owns the details.

Chronicle production hosting The production image, required certificates, storage, backups, scaling, and health checks.

Version compatibility Runtime, package, React, Node, storage, and tooling compatibility.

Security Report vulnerabilities privately and review operational hardening expectations.

The production image will not start on development settings

cratis/chronicle:latest and the versioned release tags always take the production code path. It needs a storage connection, a TLS certificate, and an encryption certificate before it starts. The TLS certificate is needed even when a proxy or load balancer terminates TLS in front of Chronicle, because Chronicle serves gRPC and HTTP over its own TLS port. The encryption certificate protects Chronicle’s internal OAuth authority and is not needed when you use an external authority instead. A Compose file that works against latest-development fails against latest for exactly this reason. See what makes a build a production build.

Release and deployment

• Pin package versions and Docker image tags. Use a specific Chronicle release tag, not latest, and never a latest-development image outside development and CI.
• Keep environment-specific configuration outside images.
• Run the full build, specs, and documentation gates before release.
• Keep a rollback plan for application code, projections, configuration, and infrastructure.
• Record which Chronicle, Arc, Components, CLI, and app versions are deployed together.

Storage and data

• Choose the Chronicle storage engine deliberately: MongoDB, PostgreSQL, Microsoft SQL Server, or SQLite.
• Run MongoDB as a replica set, even with a single node. Chronicle uses MongoDB transactions, which a standalone mongod rejects. See storage requirements.
• Back up the encryption certificates, the storage backend, and the compliance key store together, and practice restoring them in the documented order. A database backup alone is not restorable. See backup and restore.
• Plan how a restore re-applies erasures made after the backup was taken: restoring a pre-erasure backup brings deleted PII keys back. See key lifecycle.
• If you move compliance keys to a dedicated store on a system that already runs, set migrateFromDefaultStorage. Without it, existing [PII] values silently read back as empty strings. See compliance storage.
• Declare read-model indexes with [Index] instead of creating them by hand; Chronicle recreates read-model containers during replay, and hand-made indexes do not survive that. See indexing read models.
• Decide retention for replay-generated read model versions.
• Plan how projection rebuilds and event replays are executed and monitored.
• Test event type migrations before old event generations reach production.

Security and identity

• Use TLS for service-to-service and client connections, and configure real certificates, not self-signed development ones.
• Store secrets and certificate passwords in a real secret manager or platform secret store.
• Configure authentication, admin bootstrap, clients, and identity-provider certificates intentionally.
• Avoid development-only passwords, client credentials, certificates, and generated secrets in staging or production.
• In a multi-tenant application, reject requests without a valid tenant when default-namespace access is not allowed. See auth and compliance.
• Follow the private reporting path on Security for vulnerabilities.

Operations

• Enable OpenTelemetry where your environment can collect traces and metrics.
• Configure health checks for your orchestrator.
• Decide who watches failed partitions, jobs, observers, projections, and subscriptions.
• Install and configure the CLI for production diagnostics.
• Keep runbooks for replaying projections, retrying failed partitions, and verifying appended events.
• Define escalation paths: community, GitHub issues, or professional help.

User-facing application

• Decide where AuthProxy, tenant resolution, authentication, and authorization live.
• Keep generated TypeScript proxies in the frontend build so drift fails at compile time.
• Verify command validation, optimistic concurrency, and error handling from the UI.
• Use Components only after the provider, theme, and peer dependencies are configured.

Production readiness is a review loop

Revisit this page whenever you add a storage engine, identity provider, deployment region, replay strategy, or critical event type migration.