Every setting barakoCMS reads. Written from the 4.0.1 source, then brought up to 4.6.0: the keys added in 4.5.0 and 4.6.0 (tenancy mode, tenant domains in CORS, tracing, workflow concurrency and email attachments, configured rate limit policies, OpenID Connect sign-in, form email verification and per-form limits, import caps) were checked against the v4.6.0 tag. Each key is given in config form (Jwt:Key style, what you put in appsettings.json) and environment form (replace each : with a double underscore). An array element takes an index: ForwardedHeaders__KnownNetworks__0.

Start here: Home. For what changed in this major, see barakoCMS 4.0.

Three defaults account for most first-deployment surprises. All three are verifiable in the source and each is covered in its own section below.

1. JWT__Key must be 32 characters or more, or the process exits at startup. A value starting with REPLACE_THIS is also refused, because the shipped k8s secret carries a length-valid placeholder.
2. Seed__DemoContent is on in Development and off everywhere else. Turning it on seeds a demo content type and an active workflow that sends email, so in production it adds an outbound mail path.
3. The refresh cookie is marked Secure outside Development. A Production API served over plain HTTP cannot keep a browser session, because the browser will not send the cookie back.

Ordinary .NET configuration: appsettings.json, then appsettings.{Environment}.json, then environment variables. The shipped defaults live in barakoCMS/appsettings.json, and appsettings.Development.json overrides only Swagger:Enabled.

Two things are not ordinary:

Modules see only their own section. A module is handed Modules:{Name} and nothing else, so the connection string and the signing key are out of its reach (ModuleConfiguration). Some modules also declare a legacy root section they used to read; when the scoped section is empty and the legacy one is not, the legacy one is used and a warning names both. When both exist the keys are merged and the scoped value wins. The module tables below give the scoped key and the legacy key where one exists.

One key can be overridden from the database. Kubernetes__Enabled is read through IConfigurationService, which checks a SystemSetting document first, then configuration, then the default (ConfigurationService.cs). Nothing else in the core uses that path.

SKIP_SEEDER is read straight from the environment, not from configuration. Any non-empty value skips the startup seeder entirely (Program.cs).

DATABASE_URL defaults sslmode to Require and refuses an unrecognised sslmode. Npgsql's IncludeErrorDetail is on only in Development on that path, so parameter values do not reach logs in production (ResolveConnectionString).

Schema handling is not configurable: Development uses Marten's CreateOrUpdate, everything else uses CreateOnly, which creates missing objects and never alters an existing one.

Migrations have no setting of their own either. Since 4.6.0 the shipped SQL files are applied by db-migrate, an argument to the image like db-assert, run with the API stopped. It records each file in the public.barako_migrations ledger table and connects the way the app does, so give it the same ConnectionStrings__DefaultConnection and JWT__Key the deploy uses. A module's files run only where that module is enabled. See docs/migrations.md.

JwtKeyGuard.cs is the whole rule, and it runs from AddBarakoCMS:

public const int MinLength = 32;

if (string.IsNullOrWhiteSpace(key) || key.Length < MinLength)
{
    throw new System.InvalidOperationException(
        $"JWT:Key must be configured and at least {MinLength} characters (256 bits) for security.");
}

The second check refuses any key beginning REPLACE_THIS. The reason is in the same file: the shipped k8s/02-secret.yaml placeholder is 45 characters, so an operator who applies the manifests unedited would otherwise boot on a key published in this repository.

The key is read as JWT:Key first and then as the JWT__Key environment variable directly (ServiceCollectionExtensions.cs), so both forms work even where the environment provider is not wired up.

Sign-in sets barako_refresh, HttpOnly, SameSite=Lax, scoped to /api/auth/refresh. Whether it carries Secure is decided by the environment, not by the scheme of the request:

internal static bool IsSecure(HttpContext http) =>
    !http.RequestServices.GetRequiredService<IHostEnvironment>().IsDevelopment();

(RefreshTokenCookie.cs)

The file explains why it does not follow Request.IsHttps: behind a TLS-terminating proxy that is not forwarding headers, an HTTPS request arrives as HTTP and the cookie would ship without Secure on the deployment that needs it most.

The practical consequence for you: a Production or Staging API reached over plain http:// sets a Secure cookie the browser will not send back, so browser sessions cannot refresh. Either put TLS in front of it, or run the API in Development. The refresh token is also in the response body, so non-browser callers are unaffected.

All four are secrets. None of them belongs in the repository.

Rotating any of these makes everything already encrypted under it unreadable. That is why Connectors:Key is refused when it duplicates another key: one rotation would otherwise retire two unrelated controls (ConnectorOptions.cs).

Before 4.3.0 the localhost fallback applied in every environment, so a production deployment that forgot this key accepted credentialed requests from those three localhost ports. A deployment with a browser client now has to set it, and one without sees a CORS error rather than a hole.

CORS:AllowedOrigins also governs which response headers scripts may read: ETag, X-Api-Contract-Version and X-Delivery-Contract-Version are exposed to every allowed origin.

CORS:AllowTenantDomains is off by default, so the allowed origins stay exactly CORS:AllowedOrigins until it is set. A tenant domain is https only, with no port, path, wildcard, IP literal or other subdomain. With it on, responses carry Vary: Origin, and a domain saved on a tenant passes on that instance at once and on others within Multitenancy:CacheDuration (TenantDomainCorsPolicyProvider.cs).

Leaving AllowedHosts at * is what makes App:BaseUrl necessary. With host filtering wide open the API will not build links from the caller's Host header, so it returns nothing rather than let the caller choose the origin (CanonicalHost.cs).

Unset and malformed are two different failures. Unset is the 503 above, with a message naming the key to set. A value that is set but is not an absolute http or https URL throws InvalidOperationException instead, and the same check covers Feeds:SiteUrl. api.example.com with no scheme is the one to watch for: it parses as a relative URI, so it throws rather than being read as a host. The throw happens inside the request, not at startup, so the feed 500s while the host looks healthy. The message names the key and the value.

SeedUsersAsync counts users before it reads anything:

var userCount = await session.Query<User>().CountAsync();
if (userCount > 0)
{
    Console.WriteLine("[DataSeeder] Users already exist, skipping user seeding");
    return;
}

The InitialAdmin section is read after that return, so on a database with even one user both keys are ignored. Changing InitialAdmin__Password on a running deployment does nothing, and changing InitialAdmin__Username neither renames the account nor creates a second one. Reset a forgotten admin password through the API or the database, not through this key.

The generated-password note has the same condition. It is printed on the boot that creates the account and never again, it goes to Console.WriteLine rather than the logger so it does not reach a log sink, and it is not recoverable afterwards.

Roles are seeded on every boot whatever Seed:DemoContent says, and SeedRolesAsync backfills system capabilities onto roles that already exist. That is separate from the user gate above.

The default comes from DataSeeder.cs:

return configuration.GetValue("Seed:DemoContent", environment.IsDevelopment());

When it is on, three things are seeded:

• AttendanceRecord, a content type with FirstName, LastName, Email, BirthDay, JobDescription, Gender and SSN, where SSN is marked Sensitive and masked to its last four characters.
• Three sample records, deliberately unusable as personal data (Sample Employee One and friends, mail at example.com, SSN values that read SAMPLE-NOT-A-REAL-SSN-1).
• A workflow named Attendance Confirmation Email, stored active, triggering on AttendanceRecord Created with condition status = Published, whose single action is SendEmail to {{data.Email}}.

That last one is the reason to leave it off in production. Once a mail provider is configured, the demo fixture is an outbound mail path: any published AttendanceRecord mails whatever address its Email field holds. The quickstart compose file sets Seed__DemoContent to false explicitly even though it already runs as Production.

Sample login accounts (hr_manager, john_viewer, with fixed passwords) are separate: they are seeded only when ASPNETCORE_ENVIRONMENT is Development and the user table is empty, and Seed:DemoContent does not control them.

Do not map BarakoCMS__Modules__Enabled from an optional shell variable. An unset variable arrives as an empty string, and an empty string means core only. The quickstart compose file leaves it commented out for exactly this reason.

Resend:* is read at the root by the core, not by the Resend module, so these keys keep their root-level form.

With no provider module configured, the core registers a mock email service that logs instead of sending.

Set both, to the same value:

Modules__Files__Files__Scanner__Address=clamav:3310
Files__Scanner__Address=clamav:3310

They do different jobs, and the reason is the module scoping described at the top of this page. FilesModule declares no legacy root section, so it is handed Modules:Files and nothing else. The literal it reads is Files:Scanner:Address, which against that section resolves to Modules:Files:Files:Scanner:Address. Blank there registers NoFileScanner, set there registers ClamAvScanner (FilesModule.cs). ClamAvScanner then reads the same literal from the root configuration its constructor is given, so for it the key is plain Files:Scanner:Address, and that read is where it gets a host (ClamAvScanner.cs).

Either key on its own scans nothing:

• Root key only. NoFileScanner is registered and its Configured is false.
• Scoped key only. ClamAvScanner is registered, finds no address at the root, and its Configured is false too.

The upload path scans only if (_scanner.Configured), so in both cases it skips scanning and stores the file. Nothing logs a warning about it. With both keys set, an infected file gets 422 and a scanner that cannot be reached gets 503, so a test upload tells you which state you are in.

Sensitivity:Mode decides whether masking happens, not who sees through it. Since 4.6.0 a Sensitive value is shown to a role holding view_sensitive, a Hidden one to a role holding view_hidden, and both to the seeded SuperAdmin role by its id. The role names HR and SuperAdmin no longer count. That is a role grant, not a setting, so there is no key for it (SensitivityService.cs).

Every limit is a fixed window under RateLimiting:{Name} with three keys: PermitLimit, WindowSeconds and QueueLimit. A zero or negative PermitLimit or WindowSeconds, or a negative QueueLimit, stops startup with the key named; a limit cannot be turned off by setting it to zero. Raising Auth or Registration above its default logs a warning at startup.

Delivery and ApiKey are opt-in, so an upgrade refuses nothing it served before. Setting their WindowSeconds or QueueLimit without PermitLimit stops startup, since it would read as a limit that is on while it is off.

Since 4.6.0 a route in a module or the host can name a limit defined in configuration, with RequireRateLimiting("{name}"). A policy under RateLimiting:Policies:{name} takes the same three keys plus Partition. A route naming a policy nobody defined stops startup, naming the route and the policy. The names auth, telemetry, registration, site-share, delivery, logout and tls-ask are built in and cannot be used, in any case (RateLimitSetup.cs).

A rejected request gets 429.

A collector that is down costs spans, not requests: export runs on a background thread with the bounded queue and timeout above. The request path, the query string and outbound URLs are not exported. Every attribute a span carries is listed in docs/tracing.md.

/health, /health/live and /health/ready are always mapped and are not configurable. Only the memory check is tagged live; the database, disk, memory and startup-seeding checks are ready.

The quickstart compose file sets Umami__Enabled and the rest of the Umami keys in their legacy root form. Those still work and log a deprecation warning naming both sections, because UmamiAnalyticsModule declares Umami as its legacy section. The root Umami section is deprecated: the warning says it stops being read in a future major version, so a new deployment should use Modules__Analytics.Umami__*. The same holds for the AI module's root Ai section and the S3 module's Files:S3 section, the only other legacy sections a module declares.

It also sets Resend__ApiKey, and that is not a legacy form. ResendEmailModule declares no legacy section, so there is no Modules:Email.Resend equivalent to move to, and nothing warns about it. The core reads Resend:ApiKey at the root itself, as the Mail section above says. Leave it where it is.

Never commit these, and never log them:

JWT__Key, Secrets__Key, Mfa__Key, Connectors__Key, Metrics__ScrapeKey, InitialAdmin__Password, the password inside ConnectionStrings__DefaultConnection or DATABASE_URL, Resend__ApiKey, Resend__WebhookSecret, Modules__Email.Smtp__Password, Modules__Files.S3__AccessKey, Modules__Files.S3__SecretKey, Modules__Analytics.Umami__Password, Modules__Forms__Turnstile__SecretKey, RateLimiting__Renderer__Key, Tracing__Otlp__Headers, and every *__ClientSecret or *__AppSecret, which includes Oidc__Providers__{name}__ClientSecret.

CI runs Gitleaks. A hit is treated as a real incident, because rotating is the only fix once a secret is pushed.

Running docker-compose.prod.yml, seven variables use the ${VAR:?...} form, so compose refuses to start without them. That is the true minimum, and the template with all seven is .env.prod.example:

DOMAIN_API=api.example.com
[email protected]
BARAKO_TAG=4.6.0
DB_PASSWORD=<generated>
JWT_KEY=<32+ random characters>
FRONTEND_ORIGINS=https://console.example.com,https://www.example.com
ADMIN_PASSWORD=<your first sign-in>

DOMAIN_API and ACME_EMAIL are Caddy's, not the app's. The hostname has to resolve to the machine before the first start, because Caddy asks for a certificate immediately and Let's Encrypt validates over HTTP. BARAKO_TAG is required rather than defaulting to latest so the next docker compose pull is not an unplanned upgrade. The other four become JWT__Key, CORS__AllowedOrigins, InitialAdmin__Password and the password inside ConnectionStrings__DefaultConnection.

Four more variables the file passes through carry a default equal to today's behaviour, so the stack starts without them:

ASPNETCORE_ENVIRONMENT=Production, ForwardedHeaders__Enabled=true and Kubernetes__Enabled=false are written into the file, not variables, and ADMIN_USER defaults to admin. Nothing to set for those.

TLS in front of it is not optional if browsers are involved, because of the refresh cookie. Caddy is what provides it here.

Method, so you know the shape of the gap:

1. grep across the whole repository, excluding bin/ and obj/ and the test project, for GetValue, GetSection, Configuration["..."], GetConnectionString, Configure<T>(...) and BindConfiguration.
2. A second pass for configuration keys held in constants (const string ...Key = "...", SectionName, Section), since several areas name their keys once and use the constant everywhere.
3. Every options class the second pass turned up was read for its property names and default values.
4. appsettings.json, appsettings.Development.json, quickstart/docker-compose.yml, docker-compose.hub.yml, docker-compose.yml, docker-compose.prod.yml and the three .env templates were read for the keys an operator actually sets.
5. Defaults are taken from the source, not from the compose files, where the two differ. The clearest example is Seed__DemoContent: the compose file pins it to false, the code default follows the environment.

What this will miss:

• A key built at runtime from a string that grep cannot see whole. The ones of this shape that were found are listed (Lifecycle:AllowSelfTransition:{name}, Feeds:Paths:{type}, Feeds:Titles:{type}, Oidc:Providers:{name}, RateLimiting:Policies:{name} and Modules:Forms:PerForm:{slug}), but another could exist.
• Settings that are not configuration at all: SystemSetting documents edited through the admin, and anything stored in the database. Kubernetes__Enabled is the one place those two worlds meet in the core.
• Settings belonging to modules this page covers only where they read configuration. Accounting, Diagnostics, FeatureFlags, Pwa and Templates read no configuration keys of their own. Portability reads one, Portability:MaxImportRecords, listed under Content above.
• Standard ASP.NET Core and Serilog keys that barakoCMS does not read itself. ASPNETCORE_ENVIRONMENT is included because so much of the behaviour above hangs off it, and the Serilog level keys because they ship in appsettings.json, but the full set of framework keys is out of scope.

The three .env templates were read too, and every variable in them names a key documented above: quickstart/.env.example, .env.example for docker-compose.hub.yml, and .env.prod.example. Read them for the shape of a working .env, and this page for what each key does.

One thing to know about the quickstart template: a variable in .env reaches the container only if the compose file maps it to a key, and quickstart/docker-compose.yml does not map all of them. PUBLIC_API_URL and ADMIN_PORT are documented in the file as names barakoBrew's own quickstart expects, so they are deliberately unread here. The FILES__S3__* block is not mapped either, so setting it in that .env does not configure S3 storage; add the keys to the api service's environment: block yourself, in the Modules:Files.S3:* form this page gives.