Environment variable reference
How variables are named and how secrets are handled, where they come from and when a change takes effect, the cross-namespace references between services, and an index of "where is a given service's variables". The complete per-service variable tables live in the matching service section of Path B: manual per-service deployment — when deploying, that is the only place to look.
Configuration conventions
Naming rules
This system does not use the NEXT_PUBLIC_ prefix. If you are looking for it, you are treating this as an ordinary Next.js application —
that would make it impossible for one image to run different instances with different configuration. Environment variables come in two tiers, and the difference is whether the value needs to reach the browser:
| Tier | Naming | How it is read | Examples |
|---|---|---|---|
| Server-only | SCREAMING_SNAKE_CASE |
process.env.X, read on the server only |
DATABASE_URL, SITE_DOMAIN |
| Needed by the frontend | camelCase |
Forwarded to the browser through a server-side allowlist | googleClientId, staticCdnUrl |
The criterion is not "runtime versus build time" but visibility. The same runtime value is written in upper snake case for server-side use and in lower camel case for the browser.
Secrets
| Variable | Description |
|---|---|
JWT_PRIVATE_KEY / JWT_PRIVATE_KEY_PATH |
ES256 signing private key, held only by themis-auth |
JWT_PUBLIC_KEY / JWT_PUBLIC_KEY_PATH |
ES256 verification public key, held by each gateway |
IDP_SESSION_SECRET |
Session signing, required with no default, independent of the other secrets |
JWT_SIGN_ALGORITHM / JWT_VERIFY_ALGORITHM |
Defaults to ES256 |
Secrets are always injected through a Kubernetes Secret, or a
_PATHvariant points at a mounted file. Never write secrets into a Bundle'sruntimeVariables— that is plaintext.In a Bundle, secrets therefore only appear as references via
secretName/secretKey; before importing, create the matching Secret in the target namespace, see ④ of "Path A / preparing before import".
Where the variable tables are
Each service's complete variable table exists in exactly one place: the table right after "Environment variables" in that service's subsection of Path B: manual per-service deployment. It gives both the "Source" (literal / ConfigMap / Secret) and the placeholder/default, so you can create the ConfigMap and Secret straight from it. The rest of this document covers only the rules shared by all services and the references between variables.
Variables and Bundle reference: scope and conventions
This document contains no environment data. Every host, domain, port, repository address, account, secret, webhook, and Secret name is written as a placeholder (
<...>). To check the real values of an environment, look directly at that environment's Deploymentenv, ConfigMap, and Secret, and do not copy the real values back into this document. For installation steps see install-bundle.md; for upgrades and rollbacks see operations.md.
1.1 Scope
| Part | Contents |
|---|---|
| PackingTable | The operator's own runtime variables, which CRDs it installs at startup, permission requirements |
| rhea | rhea-email / rhea-payment / rhea-push / rhea-gateway / rhea-web |
| themis | themis-auth / themis-gateway / themis-web |
| thia | thia-web / thia-gateway / thia-agent / the five MCP services / thia-jobs-tick |
| tethys | tethys-shipping / tethys-gateway / tethys-web |
| Bundle | fewbox.com/v1 Bundle fields, image assembly, reconcile, deletion, import/export, and known limitations |
The example topology is "one cluster, four product namespaces", with the four namespaces reaching each other by Service short name. When splitting a product into its own cluster, the variable names and value rules do not change — only the short name becomes the reachable address of that cluster.
1.2 Where variables come from
The "Source" column in the service sections has only three possible values:
| Source | Meaning | How a change takes effect |
|---|---|---|
| Literal | Written directly into the Deployment's env |
Edit the Deployment, rolling restart |
| ConfigMap | Injected through valueFrom.configMapKeyRef or envFrom |
Edit the ConfigMap, then restart the Pod (env is not hot-reloaded) |
| Secret | Injected through valueFrom.secretKeyRef |
Edit the Secret, then restart the Pod; never put Secret content into a ConfigMap or an image |
"Required" means required for this topology to run, not a hard check in the code. A variable marked "Optional" falls back to the service's own default when left empty.
1.3 Variables common to every service
| Variable | Description | Placeholder/default |
|---|---|---|
PORT |
The port the container listens on. Must match the Service's targetPort and the probe port |
Per the service's convention, e.g. 3000 |
NODE_ENV |
production / development. Affects log verbosity, error output, and a few local fallbacks |
production |
LOG_LEVEL |
debug / info / warn / error |
info |
SERVICE_NAME |
The service identifier in logs and traces | The service name, e.g. <product>-<service> |
SHUTDOWN_TIMEOUT |
Milliseconds to wait for in-flight requests after SIGTERM. Long-task services (such as agent) need it raised, but it must be less than the Pod's terminationGracePeriodSeconds, otherwise the Pod is SIGKILLed before shutdown finishes |
30000 |
Node services read this set by default; .NET services (Shipping / PackingTable) read only PORT and use their own configuration for the rest.
Not every service uses all five — go by the actual table in each service section.
1.4 Naming and "will it reach the browser"
- Server-side variables use
SCREAMING_SNAKE_CASE; secret variable names usually carry a_KEY/_TOKEN/_SECRETsuffix. - The Next.js frontend has two configuration layers, both read at runtime (no
NEXT_PUBLIC_anywhere; one image serves several brands); the difference in naming style is not a typo:- Read server-side only (
SCREAMING_SNAKE_CASE, directly throughprocess.env.X):PORT,SITE_DOMAIN,API_DOMAIN, OIDC secrets, etc. Changing a value needs only a Pod restart, not an image rebuild. - Delivered to the browser (read on the server, forwarded via
/api/configand the SSR first paint):endpoint,wsEndpoint,googleClientId,ssoProviders, etc. stay camelCase — they become property names on the frontend configuration object verbatim.
- Read server-side only (
- Any value delivered through
/api/configreaches the browser and must never hold a secret. Secrets go only into server-side variables or Secret keyRefs. - Secret naming convention:
<service>-<purpose>, with the variable name equal to the key inside the Secret for easy cross-checking; this document only uses placeholders such as<service>-<purpose>. - Do not inject a whole Secret with
envFrom: any extra key in the Secret then also enters the process environment.
Per-service variable index
| Product line | Service | Where the table is | Notes |
|---|---|---|---|
| rhea | rhea-email |
install-manual.md | |
| rhea | rhea-payment |
install-manual.md | A missing DATABASE_URL silently falls back to in-memory |
| rhea | rhea-push |
install-manual.md | The VAPID trio is needed only for Web Push |
| rhea | rhea-gateway |
install-manual.md | CORS matches exactly, no wildcards |
| rhea | rhea-web |
install-manual.md | rheaGateway / themisGateway are Tier 2 |
| themis | themis-auth |
install-manual.md | The only issuer of secrets |
| themis | themis-gateway |
install-manual.md | The five OIDC endpoints must each declare an explicit publicPath |
| themis | themis-web |
install-manual.md | A same-origin passthrough layer, no policies |
| thia | thia-agent |
install-manual.md | Most configuration lives in agentic.yaml; env only does ${VAR} interpolation |
| thia | thia-gateway |
install-manual.md | Five proxy tables; a parse failure silently falls back to an empty array |
| thia | thia-web |
install-manual.md | Split into a server-side and a client-side table |
| thia | mcp-* |
install-manual.md | The five services share MCP_TRANSPORT / PORT / LOG_LEVEL |
| thia | thia-jobs-tick |
install-manual.md | CronJob, no environment variables |
| tethys | tethys-shipping |
install-manual.md | No kubeconfig needed inside the cluster |
| tethys | tethys-gateway |
install-manual.md | WS_PROXIES matches each path exactly |
| tethys | tethys-web |
install-manual.md | endpoint / wsEndpoint must hold public addresses |
| — | PackingTable | See "PackingTable itself" below | The operator is not a Path-B service |
PackingTable itself
PackingTable is an operator written with KubeOps that watches fewbox.com/v1 CRs. It usually runs as a single-replica Deployment,
uses the in-cluster ServiceAccount to reach the apiserver, and needs no kubeconfig; because it installs CRDs and creates resources across namespaces,
that ServiceAccount needs cluster-level permissions (cluster-admin or an equivalent ClusterRole/ClusterRoleBinding).
It does two things at startup:
- Reads the entity types of
fewbox.com/v1, translates them into CRDs and stores them (updating the schema if they already exist), and tags the CRDs withbrand=fewbox. When permissions are insufficient it only logs a warning and continues on the assumption that "the CRDs are pre-installed". - Registers four controller/finalizers: Tenant, Infrastructure, Middleware, Bundle.
Note:
Registry(fewbox.com/v1, cluster-scoped) is not among the four CRDs the operator installs itself. It is pre-installed by the platform, and the operator only reads it when materializing image pull credentials.
| Variable | Source | Required | Description | Placeholder/default |
|---|---|---|---|---|
PORT |
Literal | Yes | Operator listening port; the Docker image defaults to 8080 | 8080 |
K8S_ENDPOINT |
Local .env |
Only when running locally | The apiserver address a locally run operator connects to | https://<k8s-api> |
K8S_TOKEN |
Local .env |
Only when running locally | Access credential when running locally; do not configure it in the cluster, use the ServiceAccount | <k8s-token> |
ASPNETCORE_URLS |
Local environment | Only when running locally | Overrides the listen address, usually to avoid an occupied port | http://localhost:5299 |
Running locally: put a .env (K8S_ENDPOINT / K8S_TOKEN) in the PackingTable directory, then
ASPNETCORE_URLS=http://localhost:5299 dotnet run. Do not run the local process and the in-cluster operator against the same cluster at the same time,
otherwise the same CR is processed back and forth by two reconcilers.
Cross-namespace references
| Caller | Callee | Variables used |
|---|---|---|
| thia-web | thia-gateway | endpoint, wsEndpoint |
| thia-web | themis-gateway / rhea-gateway | themisEndpoint (user profile), rheaEndpoint (balance, ledger, plans, settlement), rheaConsoleUrl (link to the billing console; the link is not rendered when unset) |
| thia-gateway | thia-auth / thia-agent, and rhea-payment (only for /webhooks/stripe passthrough) |
AUTH_ENDPOINT, AGENT_ENDPOINT, PAYMENT_ENDPOINT and the various *_PROXIES |
| thia-agent | mcp-* | VISION_ENDPOINT, MOTION_ENDPOINT, PERCEPTION_ENDPOINT, ANALYSIS_ENDPOINT |
| tethys-web | tethys-gateway | endpoint, wsEndpoint |
| tethys-gateway | tethys-shipping | SHIPPING_ENDPOINT, SHIPPINGWS_ENDPOINT |
| themis-web | themis-gateway | GATEWAY_ENDPOINT |
| themis-gateway | themis-auth | AUTH_ENDPOINT, AUTH_OIDC_ENDPOINT |
| themis-auth | rhea-email / rhea-payment / rhea-push | EMAIL_SERVICE_URL, PAYMENT_SERVICE_URL, PUSH_SERVICE_URL, PUSH_SERVICE_TOKEN |
| rhea-payment | themis-auth (session validation) | IDP_SESSION_SECRET |
| rhea-gateway | themis-auth / rhea-payment | AUTH_ENDPOINT, PAYMENT_ENDPOINT |
| rhea-web | rhea-gateway / themis-gateway | rheaGateway, themisGateway |
⚠️ Do not mix the two address formats:
*_ENDPOINTis JSON (protocol/host/port/basePath), while*_SERVICE_URLis a complete URL (including the path, e.g.http://rhea-email/api/v1/email/send). Filling them in the wrong way round will not fail at startup — it fails silently only on the actual call.
Two secrets must hold the same value across services:
IDP_SESSION_SECRET: issued by themis-auth, parsed by themis-gateway and rhea-payment. If any of the three differs, the symptom is "sign-in succeeds but the gateway considers you signed out" or the payment page cannot resolve the user.- themis-auth's JWT signing key pair: auth signs with the private key, every gateway verifies with the public key. The public key and the current kid must come from the same pair,
otherwise every request returns
Access Denied: invalid signature. The public key can be converted to PEM from auth's/jwks.