Environment Variables Reference¶

This page lists the environment variables JAiRouter supports, when each one takes effect, what happens when it is missing, and the real differences between the shipped profiles. Every entry is taken from the bundled configuration and the code, with the location that makes it effective in parentheses. Statements marked "measured" come from real starts of this code base (prod / dev / staging) plus endpoint readings.

Read first: the three channels a variable can travel¶

Variables do not all take effect the same way. Knowing the channel is what tells you "why did setting it do nothing".

The difference between the second and third channel is the part most easily missed: JWT_SECRET must carry exactly that name because the startup gate (StartupSecretKeyChecker / StartupSecurityGate) reads the process environment instead of the property tree. Since #674 the four aliases DEV_JWT_SECRET / STAGING_JWT_SECRET / PROD_JWT_SECRET / ADMIN_PASSWORD are gone; setting them now only produces one warn line in the startup log.

Variables you must set (per profile)¶

Generate a strong JWT_SECRET with the published image:

docker run --rm sodlinken/jairouter:latest --generate-key

One production pattern that never works: setting only PROD_JWT_SECRET without JWT_SECRET. The gate reads the latter, so such a deployment never starts.

Variables worth setting (depending on the deployment shape)¶

Data storage¶

Redis (only when at least one Redis-backed switch is on)¶

The connection timeout is not an environment variable: spring.data.redis.timeout: 5000ms (persistence-base.yml:84). The image's REDIS_TIMEOUT has no binding (see #677).

Upstream model services¶

Multiple replicas¶

Which switches a multi-replica deployment must enable, and what each one changes, is covered in Multi-Replica Deployment.

Framework-level switches¶

These are not yml placeholders; they work through Spring relaxed binding. The image already sets several of them (Dockerfile:55-64):

Default differences between profiles¶

The table below shows the same keys across the three profiles. Every difference comes from application-{profile}.yml overriding the base configuration; no environment variable is required to obtain them.

What jwt.persistence.enabled actually switches off¶

This key is easily read as "turn token persistence off". It does not. What it gates is everything around persistence:

Persistence itself is not controlled by it: the component that writes and queries tokens is JwtServiceConfiguration.storeManagerJwtPersistenceService, whose condition only looks at jairouter.security.jwt.persistence.redis.enabled=false (matchIfMissing=true). Measured on prod with the switch false: after two logins, GET /api/auth/jwt/blacklist/stats returns persistedActiveTokens: 2, so tokens are in the store.

Cleanup is an independent switch, jwt.persistence.cleanup.enabled (default true); the shipped effective values are 02:00 daily, 30-day retention (measured: JWT cleanup service initialized with schedule: 0 0 2 * * ?, retention days: 30).

JWT persistence and blacklist persistence are defined in exactly one file: config/security/persistence-base.yml. Since #676config/auth/jwt.yml no longer duplicates that block, so a later import cannot silently override it.

Removed or ineffective names¶

How to check what is effective¶

• Search the startup log for JWT cleanup service initialized with schedule: and The following 1 profile is active: — that confirms the effective profile and cleanup parameters.
• GET /actuator/health: whether Redis is probed depends on REDIS_ENABLED.
• GET /api/auth/jwt/cleanup/stats and GET /api/auth/jwt/blacklist/stats need the Jairouter_Token header (JAiRouter's own JWTs travel in that header; Authorization is reserved for downstream services).
• To enumerate every placeholder and its default: git grep -n '\${' -- src/main/resources.