Configure Cratis Arc
Arc settings fail quietly: a route prefix that differs between the build and
the host returns 404 with no warning, a development-only default turns on
exception details or open discovery, and AddCratis() authenticates nobody
until a trust setting is flipped. Find the key, its default and the side that
owns it before changing code.
Where settings live
| Section | Read by | Holds |
|---|---|---|
Cratis:Arc |
AddCratisArc, AddCratis |
ArcOptions: core, commands, queries, routes, identity, tenancy |
Cratis:Chronicle |
AddCratis, WithChronicle() |
Chronicle client options (see cratis-chronicle-configuration) |
Cratis:MongoDB |
WithMongoDB() |
MongoDB connection and resilience |
Cratis:EntityFrameworkCore |
WithEntityFrameworkCore() |
EF Core connection and discovery |
ReadProtection (no Cratis: prefix) |
Startup and run time | Read-protection ceiling and measuring |
| Build properties | Proxy generator package | CratisProxies* and CratisReadProtection |
React <Arc> props |
Frontend | apiBasePath, origin, query transport |
Environment variables replace : with __:
Cratis:Arc:Tenancy:HttpHeader is Cratis__Arc__Tenancy__HttpHeader; list
items take an index. Keys are case-insensitive. The configureOptions callback
passed to AddCratisArc runs after binding and wins over configuration.
Workflow
- Start from the symptom in symptoms when there is an error or odd behavior; it names the setting.
- Look up the key in Arc options, or the MongoDB, EF Core and read-protection keys in data and protection keys.
- For the browser side, use frontend and routes, which also covers the settings that must match between build and host.
- Change one setting and restart; reproduce the symptom.
Rules that prevent the common mistakes
- Never state a default from memory. Read the reference; for a key that is not listed, read the options type.
- Route settings exist twice: as MSBuild properties for the generator and
as
GeneratedApiskeys for the host. Arc does not compare them; a mismatch is a 404. Change both in one commit. The skip and include forms are inverses. ExposeExceptionDetailsdefaults fromASPNETCORE_ENVIRONMENTalone.DOTNET_ENVIRONMENT=Developmentdoes not turn it on. Leave it off in production.- Discovery (introspection) is anonymous only in Development. Outside
Development it needs a signed-in user unless
Introspection:Rolesnarrows it orIntrospection:Enabled/IdentityDiscoveryisfalse. Do not switch a deployed host to Development to restore access. AddCratis()authenticates nobody untilTrustForwardedIdentityHeadersistrue, and that is correct only when every request passes through an ingress that authenticates callers and replaces the identity headers.ReadProtectionkeys are root-level.Cratis:Arc:ReadProtection:*has no effect. The protection mode itself is theCratisReadProtectionbuild property, not configuration.- Do not put connection strings or credentials in committed appsettings. Use secret configuration or environment variables.
- Do not change a setting on a shared or deployed environment without stating the change and its blast radius first.
References
- Read Arc options for
Cratis:Arckeys, defaults and when to change them. - Read data and protection keys for
Cratis:MongoDB,Cratis:EntityFrameworkCoreandReadProtection. - Read frontend and routes for React provider props and the generator-versus-host route settings.
- Read symptoms when starting from an error.
Related skills
- Use
cratis-arc-commandfor the proxy generator build package and its properties. - Use
cratis-arc-authentication-authorization-and-identityfor identity design. - Use
cratis-arc-hostingfor creating the host. - Use
cratis-chronicle-configurationfor Chronicle client and kernel settings.