Manual per-service deployment
The expanded view of Path A: one checklist per service, suited to auditing, customization, and item-by-item troubleshooting when "Bundle apply succeeded but nothing came up".
Path B: manual per-service deployment
This path is for troubleshooting, customization, and security auditing. Each service gets its own section, ending with the pack it corresponds to in the Bundle,
so you can cross-check the two paths against each other.
The sections are ordered by dependency: Rhea → Themis → Theia → Tethys (optional). Each service first explains what it does, then lists what you need to prepare. Every Service name is the host you fill into configuration.
Section names are basically the object names in the cluster; all of them carry the product-line label fewbox.com/family
(exceptions: mcp-* is the collective name of five MCP services, and thia-jobs-tick is a CronJob).
To find out which Deployments a given line actually has in the current cluster, just query by label:
kubectl get deploy -n <YOUR_NAMESPACE> -l fewbox.com/family=thia
Label values can be thia / themis / rhea / tethys / phoebe. Mnemosyne has no standalone service —
it runs inside thia-agent, and will only carry its own label value once it is split out.
Rhea: base services
rhea-email
What it does: transactional email — signup verification, password reset, notifications. It only handles delivery; "when to send" is decided by the caller;
themis-auth calls it through EMAIL_SERVICE_URL.
Manifest: one Deployment (stateless, no PVC) + one ClusterIP Service, port by convention 80 → 3000.
Probes hit GET /api/v1/livez and GET /api/v1/readyz — note the paths are under /api/v1 (rhea-payment's
two probes are instead at the root path; don't copy that config verbatim). Do not attach a public Ingress: it has no authentication at all;
anyone who can connect can send email, and the only legitimate caller is inside the cluster.
Prerequisites: a working SMTP account. It starts successfully without SMTP too — when SMTP_HOST is missing it falls back to
smtp.example.com, the process reports no error, and every message simply fails to send; the probes cannot detect this either, because they only look at the process.
Environment variables
| Variable | Source | Required | Description | Placeholder/default |
|---|---|---|---|---|
PORT |
Literal | Yes | Service port | 3006 |
NODE_ENV |
Literal | Yes | Runtime environment | production |
LOG_LEVEL |
ConfigMap | Optional | Log level | info |
SERVICE_NAME |
ConfigMap | Optional | Service name in logs/traces | <product>-email |
SHUTDOWN_TIMEOUT |
ConfigMap | Optional | Graceful shutdown wait (milliseconds) | 30000 |
SMTP_HOST |
ConfigMap | Yes | SMTP server. Leaving it empty falls back to smtp.example.com with no error; see above |
smtp.<provider> |
SMTP_PORT |
ConfigMap | Yes | SMTP port | 587 |
SMTP_SECURE |
ConfigMap | Yes | true for implicit TLS (usually 465), false for STARTTLS (usually 587) |
false |
SMTP_FROM |
Secret | Yes | Sender address; on a real mail service this is usually not the login account, and defaults to SMTP_USER when empty |
[email protected] |
SMTP_USER |
Secret | Yes | SMTP login or API key | <user> |
SMTP_PASS |
Secret | Yes | SMTP password or API key | <password> |
Caller configuration
# The address must include the method: themis-auth POSTs this URL directly and does not append a path itself
EMAIL_SERVICE_URL=http://rhea-email/api/v1/email/send
The request body is { "to", "subject", "body" }, and body is HTML. A failed delivery returns non-2xx — themis-auth uses that
to alert operators through rhea-push, but the signup / password-reset response is unchanged, so outsiders cannot tell that the email did not go out.
Corresponding Bundle pack: app: rhea-email
rhea-payment
What it does: payments, subscriptions, and the credits ledger. At signup themis-auth calls it through PAYMENT_SERVICE_URL to issue the signup bonus;
conversation consumption and settlement are recorded here too.
Manifest: one Deployment + one ClusterIP Service (80 → 3000) + one PostgreSQL database.
Probes hit GET /livez / GET /readyz, at the root path (rhea-email's probes are under /api/v1;
the two differ). Again no public Ingress; externally there are only two legitimate entry points: rhea-gateway's GraphQL,
and thia-gateway's POST_PROXIES passing Stripe callbacks through.
⚠️ A missing
DATABASE_URLraises no error. The process starts as usual and the UI shows a balance as usual, because it quietly switched to an in-memory store: a restart resets it to zero, and there is not a single record in the database. On a new environment confirm this item first, then look at one real credit entry.
Database
Five tables; the full schema script is in Database schema. Its unique constraint
on credit_transactions.event_id is the foundation of idempotency — without it the same payment can be
credited twice. The package catalog is a separate optional seed, covered in the "Package catalog" section of
the same page.
Credits are always granted according to credit_packages.credits, never converted from the payment amount; discounts only show up in price_minor.
Environment variables
| Variable | Source | Required | Description | Placeholder/default |
|---|---|---|---|---|
PORT |
Literal | Yes | Service port | 3000 |
NODE_ENV |
Literal | Yes | Runtime environment | production |
SERVICE_NAME |
ConfigMap | Optional | Service name in logs/traces | <product>-payment |
SHUTDOWN_TIMEOUT |
ConfigMap | Optional | Graceful shutdown wait (milliseconds) | 30000 |
DATABASE_URL |
Secret | Yes | PostgreSQL connection string. An empty value silently uses the in-memory store; see above | postgres://<user>:<pass>@<host>:5432/<db> |
STRIPE_SECRET_KEY |
Secret | Required when using Stripe | Server-side key | sk_<env>_... |
STRIPE_WEBHOOK_SECRET |
Secret | Required when using Stripe | Validates callback signatures; without it every callback is rejected | whsec_... |
STRIPE_API_VERSION |
ConfigMap | Optional | Pins the Stripe API version; recommended, so behavior does not drift after an SDK upgrade | <version> |
STRIPE_RETURN_URLS |
ConfigMap | Required when using Stripe | Multi-site return table, JSON: {"<site>":{"success":"<url>","cancel":"<url>","portal":"<url>"}}. A malformed value fails at startup (deliberately no fallback, so users are never sent back to the wrong site); the caller picks a site with site, and an unknown site gets a 400 |
<json> |
STRIPE_CHECKOUT_SUCCESS_URL |
ConfigMap | Optional | The old single-site form; used as a fallback when the request carries no site |
<url> |
STRIPE_CHECKOUT_CANCEL_URL |
ConfigMap | Optional | Same as above | <url> |
STRIPE_PORTAL_RETURN_URL |
ConfigMap | Optional | Same as above, for the self-service portal return | <url> |
PAYPAL_CLIENT_ID |
ConfigMap | Required when using PayPal | Public value | <client-id> |
PAYPAL_CLIENT_SECRET |
Secret | Required when using PayPal | Callbacks arrive at /webhooks/paypal |
<secret> |
PAYPAL_WEBHOOK_ID |
Secret | Required when using PayPal | Webhook validation id | <webhook-id> |
PAYPAL_API_BASE |
ConfigMap | Optional | Defaults to sandbox; set https://api-m.paypal.com in production |
https://api-m.<env>.paypal.com |
CURRENCY_RATES |
ConfigMap | Optional | Exchange-rate table; if unset or malformed the built-in defaults are used (a malformed value logs a warning) | <json> |
IDP_SESSION_SECRET |
Secret | Yes | The same value as themis-auth; used to decrypt the session cookie | <random-string> |
A single-site deployment uses the three STRIPE_CHECKOUT_* variables; a multi-site one uses STRIPE_RETURN_URLS.
There is no need to set both.
Interfaces (all under /api/v1 except the probes)
| Method | Path | Used by |
|---|---|---|
GET |
/packages |
Package catalog, frontend pricing page |
POST |
/checkout |
One-time purchase; creates a Stripe Checkout session |
POST |
/subscribe |
Subscription; the site in the request decides which site to return to |
POST |
/me/subscription/portal |
Self-service unsubscribe / change card / invoices |
GET |
/me/credits/balance, /me/credits/transactions |
The current user's wallet and transactions |
POST |
/me/credits/transfer |
Transfer credits to an organization or an individual |
POST |
/credits/topup, /credits/deduct |
Administrative operations (add/deduct), externally only through the gateway's ADMIN fields |
POST |
/webhooks/stripe, /webhooks/paypal |
Payment callbacks. The public entry point is thia-gateway's /webhooks/stripe, which passes them through here |
Corresponding Bundle pack: app: rhea-payment
rhea-push
What it does: delivers notifications to targets the user configures themselves — Feishu / Slack / Discord incoming webhooks,
or browser Web Push. It only transports; it stores no address book. "Who to send to" is decided by thia / tethys based on the user's
NotificationChannel, calling through PUSH_SERVICE_URL. The division of labor is the same as with rhea-email:
platform services only deliver; business services decide timing and content.
It is a purely internal service: create only a ClusterIP Service, do not attach a public Ingress, and there is no user interface.
Inbound traffic is only backend services inside the cluster; outbound is the user-configured webhook or push service. That is why
PUSH_SERVICE_TOKEN must still be set — the internal network is not a trusted network, and the semantics of this interface are
"give me an address and I will POST to it".
Prerequisites: a shared service token. VAPID keys are needed only when using Web Push.
① Generate VAPID keys (Web Push only; skip if you only use webhooks)
npx web-push generate-vapid-keys
The public key can be handed to the frontend for subscriptions; keep the private key in a Secret only. Do not put it in an image, a Bundle, or code.
② Environment variables
| Variable | Source | Required | Description | Placeholder/default |
|---|---|---|---|---|
PORT |
Literal | Yes | Service port (consistent with the other Rhea services; local debugging often uses 3007 to avoid clashing with themis-web) | 3000 |
NODE_ENV |
Literal | Yes | Runtime environment | production |
LOG_LEVEL |
ConfigMap | Optional | Log level | info |
SERVICE_NAME |
ConfigMap | Optional | Service name in logs/traces | <product>-push |
SHUTDOWN_TIMEOUT |
ConfigMap | Optional | Graceful shutdown wait (milliseconds) | 30000 |
PUSH_SERVICE_TOKEN |
Secret | Yes | Callers use Authorization: Bearer <token>. Leaving it empty means no authentication; forbidden in production |
<random-string> |
PUSH_MAX_ATTEMPTS |
ConfigMap | Optional | Delivery retry count | 3 |
PUSH_RETRY_BASE_DELAY_MS |
ConfigMap | Optional | Base retry backoff (milliseconds) | 300 |
PUSH_TIMEOUT_MS |
ConfigMap | Optional | Single delivery timeout (milliseconds) | 8000 |
PUSH_TTL_SECONDS |
ConfigMap | Optional | Message time to live | 3600 |
PUSH_TARGET_ALLOW_HTTP |
ConfigMap | Optional | Whether http targets are allowed. The code defaults to true outside production; production must set false explicitly |
false |
PUSH_TARGET_ALLOW_PRIVATE_NETWORKS |
ConfigMap | Optional | Whether loopback / private network / link-local / cloud metadata addresses are allowed; must be false in production |
false |
PUSH_TARGET_ALLOWED_HOSTS |
ConfigMap | Recommended | Allowlist of target hosts, comma-separated, subdomains included, e.g. open.feishu.cn,hooks.slack.com; empty means any public host |
<host1>,<host2> |
PUSH_VAPID_SUBJECT |
ConfigMap | No (required for Web Push) | mailto:<ops email> or the site URL |
mailto:<ops> |
PUSH_VAPID_PUBLIC_KEY |
Secret | No (required for Web Push) | The public key can be handed to the frontend for subscriptions | <vapid-public> |
PUSH_VAPID_PRIVATE_KEY |
Secret | No (required for Web Push) | When not configured the webpush channel returns 503; webhooks are unaffected | <vapid-private> |
③ Caller configuration
# By the common convention the Service port is 80 → targetPort container port; the token has the same name and value on both sides.
PUSH_SERVICE_URL=http://rhea-push/api/v1/push/send
PUSH_SERVICE_TOKEN=<same name and value as on the rhea-push side>
The webhook URL itself is a credential — anyone who has it can post messages to that channel. Service logs only record the redacted host and the end of the path, never the full address; expired subscriptions (404 / 410) must be deleted by the caller.
Corresponding Bundle pack: app: rhea-push (not yet in the Bundle)
rhea-gateway
What it does: the only GraphQL entry point for Rhea — the credits wallet and ledger, subscriptions, the package catalog, payment events, and Stripe mappings
are all read and written through it. It does not touch the database and has no user table: ask rhea-payment for billing and credits, and ask
themis-auth for "who this person is and which organization they belong to".
browser → rhea-web (admin console)
→ rhea-gateway (signature verification + permissions + aggregation) → rhea-payment (the ledger itself)
↘ themis-auth (identity and organizations)
It is the only Rhea component that needs to be exposed to the public internet. The product site's browser requests its /graphql directly (the public pricing page
reads it too), so CORS must list the real origin of each of those sites: cors() takes an exact-match array,
with no subdomain wildcard. A missing entry fails silently — the request still returns, but the response has no
Access-Control-Allow-Origin, and the frontend only sees "the balance is empty" or "the package catalog fell back to built-in values", which looks like
a data problem rather than a deployment problem.
Prerequisites: rhea-payment and themis-auth reachable; the themis-auth ES256 public key.
Environment variables
| Variable | Source | Required | Description | Placeholder/default |
|---|---|---|---|---|
PORT |
Literal | Yes | Service port | 3000 |
PAYMENT_ENDPOINT |
ConfigMap | Yes | rhea-payment address, JSON. When missing the process refuses to start (no "empty catalog" illusion) |
{"protocol":"http","host":"rhea-payment","port":80,"basePath":"api/v1"} |
AUTH_ENDPOINT |
ConfigMap | Yes | themis-auth address, same format. Organization wallet owner validation reads organizations |
{"protocol":"http","host":"themis-auth","port":80,"basePath":"api/v1"} |
JWT_PUBLIC_KEY_PATH |
Secret (file) | Yes | themis-auth public key PEM, preferably mounted as a file. Only ES256 is accepted, there is no HS256 fallback; missing also fails at startup | /etc/jwt/public.pem |
JWT_PUBLIC_KEY |
Secret | No | Same as above, inline form (\n escaped). Pick one of the two |
<pem> |
CORS |
ConfigMap | Yes | JSON array, exact match, no subdomain wildcard: ["https://<console>","https://<site>"]. A missing entry returns 200 but no Access-Control-Allow-Origin |
[] |
AJAX_TIMEOUT_MS |
ConfigMap | Optional | Upstream timeout (milliseconds) | 30000 |
PROXY |
ConfigMap | Optional | Egress proxy, the same setup as the product site; also written into HTTP(S)_PROXY |
<url> |
Permission-wise only creditPackages is anonymously readable (for the public pricing page); everything else requires sign-in, and administrative fields additionally require ADMIN.
Corresponding Bundle pack: app: rhea-gateway
rhea-web
What it does: the billing admin console, with four views available to ADMIN only — package catalog (including price changes and delisting), payment events, Stripe
mappings, and wallets (balance / transactions / add and deduct). It holds no data itself: reads and writes go through rhea-gateway; the user picker on the Stripe mapping page
reads themis-gateway (identity is not Rhea's; the Rhea gateway deliberately has no users query).
Sign-in: it is an OIDC relying party of accounts.titanides.com (public client + PKCE). Unlike themis-web,
it is not same-origin with the IdP, so it uses /api/auth/start → /api/auth/callback for the server-side code exchange — the refresh token only
goes into an HttpOnly cookie, the access token the browser gets lives only in memory, and no token ever lands anywhere JavaScript can read.
Prerequisites: rhea-gateway has a public address (the browser connects directly); themis-gateway reachable; this client is registered on the IdP side
(OIDC_CLIENTS, callback of the form https://console.titanides.com/api/auth/callback).
Environment variables
| Variable | Source | Required | Description | Placeholder/default |
|---|---|---|---|---|
PORT |
Literal | Yes | Next service port | 3000 |
rheaGateway |
ConfigMap | Yes | Tier 2 (surfaced in /api/config): the gateway address the browser connects to directly, JSON, no basePath |
{"protocol":"https","host":"rhea-gateway.titanides.com"} |
themisGateway |
ConfigMap | Yes | Tier 2: used by the user picker on the Stripe mapping page, same format | {"protocol":"https","host":"themis-gateway.titanides.com"} |
RHEA_OIDC_ISSUER |
ConfigMap | Yes | The IdP issuer | https://accounts.titanides.com |
RHEA_OIDC_CLIENT_ID |
ConfigMap | Yes | Public client (PKCE, no secret), must be registered in the IdP's OIDC_CLIENTS |
rhea-web |
RHEA_OIDC_REDIRECT_URI |
ConfigMap | Yes | Must exactly match the registered value | https://<console>/api/auth/callback |
AUTH_FLOW_TOKEN |
Secret | Yes | Signs the sign-in flow cookie (state/nonce/PKCE). No default in production; when unset, /api/auth/token returns 503 not_configured |
<random-string> |
AUTH_SESSION_TOKEN |
Secret | Yes | Encrypts the HttpOnly session cookie; must differ from the previous row, and all replicas must share it; likewise no default in production | <random-string> |
rheaGateway / themisGateway are Tier 2 keys (surfaced in /api/config and the SSR first paint; the browser needs them);
the OIDC ones are Tier 1 (read server-side only). CORS on both gateways must list this site's origin, otherwise the user search on the Stripe
mapping page is blocked by the browser.
Corresponding Bundle pack: app: rhea-web
Themis: identity
Three services in a chain, install in the order auth → gateway → web: each one needs the Service address of the previous.
browser → themis-web (login page + same-origin pass-through) → themis-gateway (signature verification + forwarding) → themis-auth (the real identity source)
If you want to expose this identity stack as a standalone OIDC service for other applications, see "Themis as a standalone OIDC service" for the configuration, the integration flow, and the acceptance checklist.
themis-auth
What it does: the single source of identity for the whole system. Registration, sign-in (username/password / Google / enterprise SSO), issuing and refreshing
access tokens; as an OIDC IdP for other sub-brands it serves /authorize, /token, /jwks,
/.well-known/openid-configuration, and /logout (RP-initiated sign-out, see "Themis as a standalone OIDC service").
It never leaves the internal network. It only accepts traffic from themis-gateway — its /users and /roles admin endpoints have no authentication of their own;
the boundary is at the gateway.
Prerequisites: PostgreSQL available; rhea-email reachable; an ES256 key pair.
① Generate the key pair
openssl ecparam -name prime256v1 -genkey -noout -out jwt-private.pem
openssl ec -in jwt-private.pem -pubout -out jwt-public.pem
② Create the tables
For a new database, run the init script directly (11 tables plus six role seeds; full text in Database schema):
psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f themis-auth-init.sql
The script creates no user at all — after installation nobody can sign in. Register an administrator and grant the role yourself; the steps are in the "The admin account" section of the same page.
③ Configuration
| Variable | Source | Required | Description | Placeholder/default |
|---|---|---|---|---|
PORT |
Literal | Yes | Service port | 3000 |
NODE_ENV |
Literal | Yes | Runtime environment | production |
LOG_LEVEL |
Literal | Optional | Log level | info |
SERVICE_NAME |
Literal | Optional | Service name in logs/traces | <product>-auth |
SHUTDOWN_TIMEOUT |
Literal | Optional | Graceful shutdown wait (milliseconds) | 30000 |
JWT_EXPIRES_IN |
Literal | Yes | Access token lifetime | 24h |
REFRESH_TOKEN_EXPIRES_IN |
Literal | Yes | Refresh token lifetime; should match the session configuration | 7d |
BCRYPT_ROUNDS |
Literal | Optional | Password hashing cost | 12 |
GOOGLE_CLIENTID |
ConfigMap | Optional | Only when Google sign-in is enabled | <google-client-id> |
SIGNUP_VERIFY_URL |
ConfigMap | Yes | Template for the frontend address the verification email links back to | https://<web-host>/{locale}/verify-email |
PASSWORD_RESET_URL |
ConfigMap | Yes | Template for the frontend address the password-reset email links back to | https://<web-host>/{locale}/reset-password |
SIGNUP_BONUS_CREDITS |
ConfigMap | Optional | Signup bonus credits; 0 disables it | 0 |
OIDC_CALLBACK_URL |
ConfigMap | Optional | The single callback address when this service acts as an OIDC client for a third-party IdP; set it only when enterprise SSO is enabled | https://<accounts-origin>/api/v1/oidc/callback |
SSO_PROVIDERS (alias OIDC_PROVIDERS) |
ConfigMap | Optional | Third-party IdP registry, a JSON array; see "Enterprise SSO" below. When it contains clientSecret, the whole value should go into a Secret |
[{"key":"<key>","issuer":"<issuer>","clientId":"<id>","clientSecret":"<secret>","scopes":"openid profile"}] |
JWT_SIGN_ALGORITHM |
ConfigMap | Yes | Defaults to ES256. Do not change it to HS256 — that hands signing authority to every gateway holding the key |
ES256 |
JWT_PRIVATE_KEY_PATH |
ConfigMap | Required for ES256 | Private key PEM file path (Secret mounted as a file). Mounting files is safer than writing keys into environment variables | <path> |
JWT_PUBLIC_KEY_PATH |
ConfigMap | Required for ES256 | Public key PEM file path; gateways use it to verify signatures | <path> |
OIDC_ISSUER |
ConfigMap | Yes | Public issuer, e.g. https://accounts.titanides.com, no trailing slash; the four OIDC endpoints are derived from it |
https://<accounts-origin> |
OIDC_KEY_ID |
ConfigMap | Yes | Key id (kid) in the JWKS; must correspond to the signing key | <kid> |
OIDC_CLIENTS |
ConfigMap | Yes | RPs allowed to integrate: three exact allowlists — client_id, redirect_uris, post_logout_redirect_uris, as JSON. Empty = deny everything |
<json> |
LOGIN_URL |
ConfigMap | Yes | The login page to redirect to when /authorize is accessed without a session |
https://<web-host>/<locale>/signin |
IDP_SESSION_TTL_SECONDS |
ConfigMap | Optional | IdP session cookie lifetime | 604800 |
AUTH_CODE_TTL_SECONDS |
ConfigMap | Optional | Authorization code lifetime | 60 |
ID_TOKEN_EXPIRES_IN |
ConfigMap | Optional | id_token lifetime | 1h |
IDP_SESSION_SECRET |
Secret | Yes | Sealing key for the session cookie and flow state (or the _PATH variant). No default value; if missing, startup fails immediately. themis-gateway and rhea-payment must share the same value |
<random-string> |
DATABASE_URL |
Secret | Yes | PostgreSQL connection string. When sharing an instance with other services, specify a dedicated schema or a dedicated database | postgres://<user>:<pass>@<host>:5432/<db> |
EMAIL_SERVICE_URL |
ConfigMap | Yes | The address of rhea-email |
http://<email-svc>:<port>/api/v1 |
PAYMENT_SERVICE_URL |
ConfigMap | Yes | The top-up endpoint of rhea-payment (a complete URL) |
http://<payment-svc>:<port>/api/v1/credits/topup |
PUSH_SERVICE_URL |
ConfigMap | Optional | Email delivery failure alerts; only effective together with ALERT_WEBHOOK_URL |
http://<push-svc>:<port>/api/v1 |
PUSH_SERVICE_TOKEN |
Secret | Optional | The service token shared with rhea-push |
<token> |
ALERT_WEBHOOK_URL |
Secret | Optional | Ops group webhook; a credential, put it in a Secret | <webhook-url> |
ALERT_WEBHOOK_FORMAT |
ConfigMap | Optional | raw / feishu / slack / discord; must match the target channel |
raw |
ALERT_WEBHOOK_KEYWORD |
ConfigMap | Optional | When the Feishu group bot has the "custom keyword" check enabled, copy one keyword verbatim from the bot settings (no quotes). Feishu lets the message through if any keyword matches, so one is enough; leave it unset if the bot has no check | <keyword> |
ALERT_COOLDOWN_SECONDS |
ConfigMap | Optional | Cooldown per alert type, default 60 seconds | 60 |
Alert contents include only the email type, the redacted recipient (a***@example.com), the error message, and the service name;
the token in verification / reset links never enters logs or alerts. The same type sends only one alert within the cooldown window,
so an SMTP outage does not post one message to the group for every signup request.
OIDC_CLIENTS is a JSON array; each item is one RP:
[
{
"client_id": "tethys-web",
"redirect_uris": ["https://console.titanides.com/api/auth/callback"],
"post_logout_redirect_uris": ["https://console.titanides.com/"]
}
]
redirect_uris: authorization-code callback addresses, byte-for-byte exact match; one extra path segment is enough to fail.post_logout_redirect_uris: addresses allowed to redirect back to after sign-out, also exact match, and they may only point at public pages (usually the site root/). If unset it falls back to "the same-origin root ofredirect_uris" — a compatibility path left for early clients; write it explicitly for new integrations, otherwise any path under that domain can be used as a sign-out redirect target.- These are public clients with no
client_secret; security is provided by PKCE (S256).
JWT_EXPIRES_IN, REFRESH_TOKEN_EXPIRES_IN, IDP_SESSION_TTL_SECONDS, AUTH_CODE_TTL_SECONDS
all have sensible defaults and usually need no change.
Enterprise SSO (auth as an OIDC client): the user authenticates on the enterprise IdP's (Microsoft Entra, Okta, Keycloak, …) login page; back on this service they only get this service's session cookie, and the browser is then sent back to the original page. All vendor differences live in the registry; no vendor-specific content appears in code or URLs:
[{"key":"entra","issuer":"https://login.microsoftonline.com/<tenant>/v2.0","clientId":"<client ID of the app registration>","clientSecret":"<client secret>","scopes":"openid profile email","claimMapping":{"displayName":"name","orgId":"tid"},"usernamePrefix":"ms"}]
OIDC_PROVIDERSin older deployments is an alias forSSO_PROVIDERS; use one or the other.key: the identifier used by the login-page button and by/api/v1/oidc/start?provider=<key>.issuer: exact match (including whether there is a trailing slash, which must agree with the enterprise IdP's discovery document).claimMapping: maps display name / organization id / organization name to the vendor's claim names; without anorgIdmapping no organization is created automatically.OIDC_CALLBACK_URL: the single callback address reported to the enterprise IdP, for examplehttps://accounts.titanides.com/api/v1/oidc/callback. Must be same-origin with the login page — the flow's state/nonce/PKCE live in a same-origin cookie, so a different domain is guaranteed to fail validation.
After a successful sign-in it only sets fewbox_idp_session and 302s to the return supplied by the caller (a same-origin relative path, default /);
applications that need tokens go through the /authorize authorization-code flow, and no credential appears in the URL. On failure it 302s back to
LOGIN_URL?sso_error=<reason>&return=<path>; the user sees a hint on the login page and can retry directly.
④ Deploy
apiVersion: apps/v1
kind: Deployment
metadata:
name: themis-auth
namespace: <YOUR_NAMESPACE>
spec:
replicas: 1
selector:
matchLabels: { app: themis-auth }
template:
metadata:
labels: { app: themis-auth }
spec:
containers:
- name: themis-auth
image: <YOUR_REGISTRY>/fewbox-themis-auth:<VERSION>
ports:
- containerPort: 3000
envFrom:
- configMapRef: { name: themis-auth-config }
- secretRef: { name: themis-auth-secret }
volumeMounts:
- name: keys
mountPath: /etc/themis-keys
readOnly: true
readinessProbe:
httpGet: { path: /api/v1/readyz, port: 3000 }
livenessProbe:
httpGet: { path: /api/v1/livez, port: 3000 }
volumes:
- name: keys
secret: { secretName: themis-auth-keys }
---
apiVersion: v1
kind: Service
metadata:
name: themis-auth
namespace: <YOUR_NAMESPACE>
spec:
type: ClusterIP
ports:
- port: 80
targetPort: 3000
selector: { app: themis-auth }
Verify: Pod READY; inside the container wget -qO- localhost:3000/api/v1/livez returns something (the probe path is under
/api/v1; writing /livez gives 404 and the probe keeps failing); deliberately delete IDP_SESSION_SECRET and restart — it should
fail to start. That is an intentional failure posture, not a defect.
Corresponding Bundle pack: app: themis-auth
themis-gateway
What it does: the only external entry point for the identity domain; it does two things — ① the management GraphQL (users / roles / organizations) used by the admin console; ② forwards the five OIDC endpoints (including sign-out) to themis-auth unchanged, so auth never leaves the internal network. JWT verification and the ADMIN gate also live at this layer.
Prerequisites: themis-auth is ready.
Configuration
| Variable | Source | Required | Description | Placeholder/default |
|---|---|---|---|---|
PORT |
Literal | Yes | Gateway port | 4004 |
CORS |
ConfigMap | Yes | Allowed origins, JSON array | ["https://<web-host>"] |
AUTH_ENDPOINT |
ConfigMap | Yes | auth's REST API (sign-in/sign-up/organizations/profile), JSON, with basePath api/v1 |
{"protocol":"http","host":"themis-auth","port":80,"basePath":"api/v1"} |
AUTH_OIDC_ENDPOINT |
ConfigMap | Yes | auth's IdP protocol endpoints (/authorize, /token, /jwks), no basePath — they are at auth's root path |
{"protocol":"http","host":"themis-auth","port":80} |
JWT_VERIFY_ALGORITHM |
ConfigMap | Yes | Verification algorithm; must match auth's signing algorithm | ES256 |
JWT_PUBLIC_KEY_PATH |
ConfigMap | Yes | The same public key as auth (PEM file path) | <path> |
REDIRECT_PROXIES |
ConfigMap | Yes | 3xx pass-through table: /authorize, /logout, OIDC start/callback, SSO assert |
[{"endpoint":"AUTH_OIDC","path":"authorize","publicPath":"/authorize"}] |
GET_PROXIES |
ConfigMap | Yes | GET pass-through table: JWKS, discovery, /me, organizations, signup verification, etc. | [{"endpoint":"AUTH_OIDC","path":"jwks","publicPath":"/jwks"}] |
POST_PROXIES |
ConfigMap | Yes | POST pass-through table: token, sign-in/sign-up, password reset, sign-out (with clearSessionCookie), organization members |
[{"endpoint":"AUTH","path":"signin/form","publicPath":"/api/v1/signin/form"}] |
PUT_PROXIES |
ConfigMap | Optional | PUT pass-through table: change password, change profile, change organization | [{"endpoint":"AUTH","path":"me","publicPath":"/api/v1/me"}] |
DELETE_PROXIES |
ConfigMap | Optional | DELETE pass-through table: delete account, remove member | [{"endpoint":"AUTH","path":"me","publicPath":"/api/v1/me"}] |
IDP_SESSION_SECRET |
Secret | Yes | Exactly the same value as themis-auth; used to decrypt the session cookie | <random-string> |
The five endpoints must explicitly set publicPath:
REDIRECT_PROXIES=[{"endpoint":"AUTH_OIDC","path":"authorize","publicPath":"/authorize"},{"endpoint":"AUTH_OIDC","path":"logout","publicPath":"/logout"}]
POST_PROXIES=[{"endpoint":"AUTH_OIDC","path":"token","publicPath":"/token"}]
GET_PROXIES=[{"endpoint":"AUTH_OIDC","path":"jwks","publicPath":"/jwks"},{"endpoint":"AUTH_OIDC","path":".well-known/openid-configuration","publicPath":"/.well-known/openid-configuration"}]
Without them the default paths look like /auth_oidc/authorize, and OIDC clients cannot find them.
/logout must be in REDIRECT_PROXIES: auth's response is a 302 with Set-Cookie (clearing the session cookie).
Handled as an ordinary GET proxy, the 302 is swallowed as a response body, and the browser receives neither the redirect nor the cookie-clearing instruction.
Deploy: a Deployment + ClusterIP Service shaped like auth's (80 → 3000), probes /livez, /readyz.
Verify: the issuer returned by /.well-known/openid-configuration should equal OIDC_ISSUER; with an admin
token query users via /graphql; a non-admin should be rejected.
Corresponding Bundle pack: app: themis-gateway
themis-web
What it does: the login page for accounts.titanides.com, and also the same-origin pass-through layer. One domain can only bind one service, so
/authorize, /token, /jwks, /.well-known, /logout, and /api/v1/* are forwarded by this service to
themis-gateway. This layer makes no policy decisions; the allowlist lives in the gateway alone.
Configuration
| Variable | Source | Required | Description | Placeholder/default |
|---|---|---|---|---|
PORT |
Literal | Yes | Next service port | 3000 |
GATEWAY_ENDPOINT |
ConfigMap | Yes | themis-gateway address. Read server-side only, never sent to the browser; if unset, protocol paths return 502 with the reason written in the response | http://themis-gateway |
googleClientId |
ConfigMap | Optional | Same as auth's GOOGLE_CLIENTID; if unset the button is hidden |
<google-client-id> |
ssoProviders |
ConfigMap | Optional | Button metadata [{"key","label","logoUrl"}], kept consistent with auth's registry; if unset the corresponding buttons are not rendered. key must match the key in auth's registry, and label can be a plain string or an object keyed by language |
[] |
Deploy: Deployment + Service (80 → 3000); point accounts.titanides.com at it at the edge.
Verify: open accounts.titanides.com and go through signup → receive email → verify → sign in; then access
https://accounts.titanides.com/.well-known/openid-configuration directly — if you get the document, pass-through works.
The pass-through paths are a fixed list baked into the image (
app/authorize,app/token,app/jwks,app/.well-known/openid-configuration,app/logout), not configuration. Adding paths can only be done by upgrading the image — if you only change the gateway'sREDIRECT_PROXIESand the image is still old, accessing/logoutfalls through to Next's own 404.
Corresponding Bundle pack: app: themis-web
Sign-out chain
Signing out spans three services. If any link is missing, the symptom is not "cannot sign out" but two subtler things: a 404 on the sign-out page, or the next sign-in goes straight through silently (the IdP session was not cleared).
- The application side (e.g.
tethys-web) first deletes the refresh token, blacklists the access token'sjti, and clears the token in the browser; then returns the sign-out addressTETHYS_OIDC_LOGOUT_ENDPOINT(default${TETHYS_OIDC_ISSUER}/logout). - The browser navigates the full page to that address. This step cannot be skipped: the session cookie is
HttpOnly; SameSite=Lax, and onlyaccounts.titanides.comitself can clear it. themis-webpasses/logoutsame-origin through tothemis-gateway(like/authorizeit is a 302 +Set-Cookie, so it must go throughREDIRECT_PROXIES).themis-authvalidatesid_token_hint(used only to identify which RP; expired ones are accepted) andpost_logout_redirect_uris, clearsfewbox_idp_session, and 302s back to the registered address.
Configuration at each place:
| Location | What to configure |
|---|---|
themis-auth's OIDC_CLIENTS |
The RP's redirect_uris + post_logout_redirect_uris |
themis-gateway's REDIRECT_PROXIES |
{"endpoint":"AUTH_OIDC","path":"logout","publicPath":"/logout"} |
The themis-web image |
Contains the /logout pass-through route |
tethys-web |
TETHYS_OIDC_ISSUER / CLIENT_ID / REDIRECT_URI; post_logout_redirect_uris must include the console's ${origin}/ |
Verify: curl -I "https://accounts.titanides.com/logout?client_id=<client_id>"; the response header should carry
x-powered-by: Express (from the gateway). If you see x-powered-by: Next.js plus a 404, the request stopped at
themis-web — the image has no /logout route.
Theia: AI Agent
thia-agent
What it does: the agent engine — multiple LLM providers and failover, MCP tool integration, skills and long-term memory; it is also the execution body for heartbeats and
scheduled jobs (thia-jobs-tick knocks on it every 5 minutes). It is both an API service and a background job process,
in the same Pod.
Manifest: one Deployment + one ClusterIP Service (80 → 3000) + the same PostgreSQL database.
Probes hit the root paths GET /livez, GET /readyz; GET /metrics serves Prometheus-format metrics.
Do not attach a public Ingress: it does not verify JWTs, it only trusts the x-user-id header minted by the gateway — anything that can connect directly can impersonate any user.
⚠️
/readyzonly means "the process is still there", not that it works. It does not check the database, the configuration, or MCP. If the database is unreachable or the configuration failed to load, the Pod is still Ready. The real liveness check isAgentic system readyin the logs.
Database: this database must have the pgvector extension (the memory vector column is vector(1024)). The code does not create tables;
all 22 tables come from the init script, whose full text is in Database schema:
psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f thia-agent-init-db.sql
A missing table raises no error — startup succeeds, all probes are green, and only the first time a feature queries that table do you get a 500.
Where configuration comes from: most configuration is not in environment variables but in the mounted config/agentic.yaml
(LLM provider table, MCP server table, memory, billing unit prices, job switches). Environment variables exist to interpolate ${VAR} into that YAML —
the YAML says apiKey: '${KIMI_API_KEY}' and the real value lives in a Secret.
⚠️ The image contains no
config/and noskills/. Packaging copies onlydistand dependencies, and.dockerignorealso excludes the skills directory. Soagentic.yamlmust be mounted in via a ConfigMap (same for skills); do not expect the image to carry them. When it is not mounted, the startup log saysAgentic config file not found, skipping initialization, and the process keeps listening with probes still passing — only conversations and tools are completely non-functional.
Environment variables
| Variable | Source | Required | Description | Placeholder/default |
|---|---|---|---|---|
PORT |
Literal | Yes | Service port | 3000 |
NODE_ENV |
Literal | Yes | Runtime environment | production |
LOG_LEVEL |
ConfigMap | Optional | Log level | info |
SERVICE_NAME |
ConfigMap | Optional | Service name in logs/traces | <product>-agent |
SHUTDOWN_TIMEOUT |
ConfigMap | Optional | Graceful shutdown wait (milliseconds). Must be less than the Pod's terminationGracePeriodSeconds, otherwise long tasks are SIGKILLed while wrapping up |
30000 |
DEBUG_MODE |
ConfigMap | — | A debug switch present in deployments; the current code does not read it directly and it looks like a legacy variable | false |
BROWSER_TOOLS_ENABLED |
ConfigMap | Optional | When true, browser tools are enabled for the model |
false |
OPENROUTER_API_KEY |
Secret | Optional | OpenRouter inference key | <key> |
DEEPSEEK_API_KEY |
Secret | Optional | DeepSeek inference key. The shipped tool-call provider uses it | <key> |
BYTEPLUS_API_KEY |
Secret | Optional | BytePlus / Volcano Ark inference key | <key> |
KIMI_API_KEY |
Secret | Optional | Kimi (Moonshot) inference key. The shipped main loop uses it | <key> |
EMBEDDING_API_KEY |
Secret | Optional | Embedding service key | <key> |
BRAVE_API_KEY |
Secret | Optional | Brave search key | <key> |
TAVILY_ENDPOINT |
ConfigMap | Optional | Tavily search MCP endpoint | http://<tavily-host>/mcp |
VISION_ENDPOINT |
ConfigMap | Depending on how many MCPs you install | Vision MCP endpoint, of the form http://mcp-vision/mcp, including the /mcp path |
http://<vision-svc>/mcp |
MOTION_ENDPOINT |
ConfigMap | Depending on how many MCPs you install | Video / motion MCP endpoint, same form | http://<motion-svc>/mcp |
PERCEPTION_ENDPOINT |
ConfigMap | Depending on how many MCPs you install | Perception MCP endpoint, same form | http://<perception-svc>/mcp |
ANALYSIS_ENDPOINT |
ConfigMap | Depending on how many MCPs you install | Read-only SQL analysis MCP endpoint (ADMIN only) | http://<analysis-svc>/mcp |
FETCH_ENDPOINT |
ConfigMap | — | Present in deployments; the current code does not read it directly (web-fetch capability is declared in the agent configuration's MCP section) | http://<fetch-svc>/mcp |
DATABASE_URL |
Secret | Yes | PostgreSQL connection string; this is what store.postgresUrl in the YAML references |
postgres://<user>:<pass>@<host>:5432/<db> |
ALERT_WEBHOOK_URL |
Secret | Optional | Runtime alert callback address; the value is a credential, put it in a Secret | <webhook-url> |
SHARE_ACCESS_SECRET |
Secret | Optional | Signs share access tokens; if unset, clicking "unlock" errors out directly instead of silently letting you through | <random-string> |
POD_NAME |
Downward API | With multiple replicas | Used to distinguish replica identity | <pod-name> |
In the shipped configuration the main loop uses
${KIMI_API_KEY}and tool calls use${DEEPSEEK_API_KEY}— whichever provider is enabled in the YAML, you owe that key. A variable name that does not appear in a code search may still take effect: it can be referenced from the YAML (see above).
MCP services are registered in the YAML, not auto-discovered. After installing an MCP service, add an entry to mcp.servers[]
(for the full fields, the three transports, pricing, and permissions, see MCP tool services):
- id: 'fewbox-remote-vision'
name: 'FewBox Remote Vision'
enabled: true
transport:
type: 'streamable-http'
url: '${VISION_ENDPOINT}'
pricing: { pricePerCall: 0 } # per-tool pricing goes here; per-model / per-usage pricing goes on the provider side
resilience:
callTimeoutMs: 300000 # image / video generation is a long task; don't use the default 30s
id can be anything; the tool name is the contract: at runtime services are found by tool name (the heartbeat uses
findServerForTool('fetch_feed') to fetch RSS), so if mcp-fetch is not registered, any routine with a fetch source logs a
Routine runtime fetch NOT available warning at startup, and then falls back to a model round every single time.
The mcp-analysis entry needs two extra fields — permissions and routine exemption:
requiredRoles: ['ADMIN'] # only ADMIN can see / call it
availableInRoutines: false # heartbeats never run SQL automatically
⚠️ When
${VAR}is unset the whole key is dropped. The interpolation logic returnsundefinedfor "the whole value is a single variable", and this configuration must then pass zod validation; a missing required item shows up in the log asFailed to load agentic configuration. But the process does not exit: that error is swallowed, the HTTP service keeps listening, and/livez,/readyzare all green — the symptom is "installed, can connect, but conversations don't go out". Judge only by whether the startup log containsAgentic system readyandEnvironment variable X is not set.
⚠️
poolSizeis the per-Pod connection count. When several replicas share one PostgreSQL pool,replica count × poolSize + 1(the 1 is the LISTEN connection) must stay within the session limit allowed on the database side.
Verify: curl http://thia-agent/livez; http://thia-agent/docs opening Swagger only proves the process is installed.
Then call three endpoints:
curl http://thia-agent/api/v1/agents # returns a list → database and migrations are in place
curl -H 'x-user-id: <REAL_USER_ID>' http://thia-agent/api/v1/me/conversations
curl http://thia-agent/.well-known/agent-card.json # 200 → agentic config loaded (503 means not loaded)
None of these three verify JWT at the application layer (/me/* only reads the x-user-id header), so if they return, the process, database, and configuration are all in place;
conversely, only when all of them 404 / 500 do you need to look at networking and migrations. Finally send one conversation from thia-web; the log should show
each MCP service connecting successfully one by one.
Corresponding Bundle pack: app: thia-agent
thia-gateway
What it does: the unified entry point for thia-web and the browser extension. The browser knows only this: GraphQL (/graphql),
SSE (/stream), and file uploads all enter here; JWT verification also happens at this layer. There are also several "proxy tables" that forward paths unchanged to
thia-agent / themis-auth / rhea-payment, for streaming events, WebSockets, and payment callbacks.
Manifest: one Deployment + one ClusterIP Service (80 → 3000). Probes hit the root paths
GET /livez, GET /readyz. It needs a public domain: thia-web's endpoint / wsEndpoint both point at it.
A2A clients do not go through here: the agent card and JSON-RPC (
/.well-known/agent-card.json,/a2a) hang offthia-agent, which itself has no inbound authentication. To offer A2A externally you must add a proxy on the gateway or open a separate Ingress, and add authentication at that layer yourself.
⚠️
PORTmust not be deleted. The image setsPORT=3000, and the code has no fallback default — if the variable is gone, Node listens on a random port; the Pod shows Running but the Service cannot reach it, and the probe keeps failing.
Environment variables
| Variable | Source | Required | Description | Placeholder/default |
|---|---|---|---|---|
PORT |
Literal | Yes | Gateway port. The code has no default; delete it and Node listens on a random port | 3000 |
CORS |
ConfigMap | Yes | Allowed origins array, JSON. A JSON typo only prints one line [Config] Invalid JSON in env CORS and falls back to ["http://localhost:3000"]; the symptom is the browser reporting CORS while curl works fine |
["https://<web-host>"] |
JWT_PUBLIC_KEY |
Secret | Yes | The ES256 public key paired with themis-auth's current signing key (PEM). If missing or malformed, the process exits 1 at startup; JWT_PUBLIC_KEY_PATH can mount it as a file instead |
<pem> |
JWT_VERIFY_ALGORITHM |
ConfigMap | Optional | If set it can only be ES256; anything else fails startup (HS256 unsupported) |
ES256 |
AUTH_ENDPOINT |
ConfigMap | Yes | Identity service REST endpoint, JSON | {"protocol":"http","host":"themis-auth","port":80,"basePath":"api/v1"} |
AGENT_ENDPOINT |
ConfigMap | Yes | Agent service endpoint, JSON | {"protocol":"http","host":"thia-agent","port":80} |
PAYMENT_ENDPOINT |
ConfigMap | When using payment callbacks | Only used for the POST_PROXIES payment webhook pass-through (endpoint: "PAYMENT"); the GraphQL payment fields have moved to rhea-gateway and no longer read it. Omit it if you do not proxy webhooks |
{"protocol":"http","host":"rhea-payment","port":80} |
GET_PROXIES |
ConfigMap | By feature | GET proxy table, JSON array, elements {endpoint, path, publicPath?}. endpoint is one of the service names above, path is the backend path, and the public path defaults to /<lowercased endpoint>/<path> |
[] |
GET_SSE_PROXIES |
ConfigMap | By feature | GET SSE proxy table, same element format. thia-web's conversation event stream uses this one |
[{"endpoint":"AGENT","path":"events"}] |
POST_PROXIES |
ConfigMap | By feature | POST proxy table, same element format. Payment callbacks use this one | [{"endpoint":"PAYMENT","path":"api/v1/webhooks/:provider"}] |
POST_SSE_PROXIES |
ConfigMap | By feature | POST SSE proxy table, same element format | [] |
WS_PROXIES |
ConfigMap | By feature | WebSocket proxy table, same element format. thia-web does not use it today — the conversation stream is a WebSocket on /graphql, handled natively by the gateway |
[] |
IMAGE_SUPPORTED_TYPES |
ConfigMap | Optional | Image MIME types passed through verbatim; images not in the list are converted to jpeg | ["image/png","image/jpeg","image/webp","image/gif"] |
IMAGE_MAX_SIZE_BYTES |
ConfigMap | Optional | Size limit for verbatim image pass-through (bytes) | 10485760 |
UPLOAD_MAX_FILE_SIZE |
ConfigMap | Optional | Upload size limit per file (bytes). The sample ConfigMap in the repository says 6 — if you copy it, the browser grabbing a dozen images at once gets a 413 |
10000000 |
UPLOAD_MAX_FILES |
ConfigMap | Optional | Files per upload (the browser grabs at most 12 images at a time; leave headroom) | 20 |
AJAX_TIMEOUT_MS |
ConfigMap | Optional | Timeout for forwarding to the backend (milliseconds). Code default is 30000 (the 600000 in the sample file is not the default). The image / video generation routes are long tasks; in production set it explicitly to 600000 |
600000 |
GRAPHQL_BODY_LIMIT |
ConfigMap | Optional | GraphQL JSON body limit, default 1mb; there are two layers with the edge nginx's client_max_body_size, and both must be sufficient |
1mb |
ENABLE_HTTPS |
ConfigMap | Optional | When true the gateway terminates TLS itself |
false |
SSL_KEY_PATH |
ConfigMap | Optional | TLS private key file path (when the Secret is mounted as files) | <path> |
SSL_CERT_PATH |
ConfigMap | Optional | TLS certificate file path | <path> |
TRACING_ENABLED |
ConfigMap | Optional | Turns on OpenTelemetry tracing | false |
TRACING_DEBUG |
ConfigMap | Optional | Turns on OTel internal diagnostic logs; troubleshooting only | false |
OTEL_SERVICE_NAME |
ConfigMap | Optional | Service name in traces | <product>-gateway |
OTEL_EXPORTER_OTLP_ENDPOINT |
ConfigMap | Optional | OTLP export address | http://<collector>:4318/v1/traces |
JWT_OPERATION_NAME_WHITELIST |
ConfigMap | — | Legacy variable: the current gateway code no longer reads it; you can remove it from the deployment | — |
⚠️ The
endpointJSON has no automatic prefix. Proxies concatenatepathverbatim, so ifAUTH_ENDPOINThas nobasePathyou must writeapi/v1/...in full in eachpath.⚠️ A proxy table that fails to parse = that proxy does not exist. All five tables go through the same
parseJsonEnv: on invalid JSON the whole thing falls back to an empty array, leaving only one error line such as[Config] Invalid JSON in env GET_SSE_PROXIES, and startup still succeeds. So after configuring, check the startup log for the corresponding[SSE PROXY] /agent/events -> …lines, not just whether the process came up.
Proxies that must exist (whichever is missing, the corresponding feature is "the UI looks fine, the call 404s"):
| Feature | Table | Entry |
|---|---|---|
| Agent event stream (SSE) | GET_SSE_PROXIES |
{"endpoint":"AGENT","path":"events"} → public path /agent/events; thia-web's conversation stream uses this one |
| Payment callbacks | POST_PROXIES |
{"endpoint":"PAYMENT","path":"api/v1/webhooks/:provider"} → public path /payment/api/v1/webhooks/:provider, which you fill into the Webhook URL in the Stripe dashboard |
The conversation interaction stream needs no proxy: it is graphql-transport-ws over /graphql, handled natively by the gateway.
WS_PROXIES is for other integrations that need a direct WebSocket (the console's tethys-gateway uses it, see the Tethys section).
⚠️ Proxies do not enforce authentication. Requests with a token are verified and get an
x-user-idminted; requests without a token are forwarded all the same, just with no identity header. So a proxy may only point at paths that are already meant to be publicly accessible — puttingthia-agent's admin routes (such as/api/v1/jobs/tick,/api/v1/billing/settle) behind one is the same as exposing them to the public internet.
Verify: curl https://gateway.titanides.com/livez returns {"status":"ok"}. Note that /readyz also only means the process is listening;
it does not check whether AUTH_ENDPOINT / AGENT_ENDPOINT are reachable — if those are misconfigured the probe is just as green. With a user token call
POST /graphql and query myConversations (without a token it should return
Access Denied: Authentication required); if it returns a list, both signature verification and the agent chain work. Then look in the startup log for the
[GET PROXY] /x -> http://… line printed for each proxy table, and confirm the composed path matches the backend route.
Corresponding Bundle pack: app: thia-gateway
thia-web
What it does: the web application the team uses — marketing pages, curated pages, and the chat interface all live here. It is also the OIDC RP:
the browser only talks to it; the sign-in redirect, the callback code exchange, and sign-out all happen in its /api/auth/* routes,
and backend services never face the browser directly.
Manifest: one Deployment (Next.js standalone, node server.js, no PVC) + one ClusterIP
Service, port 80 → 3000.
⚠️ It has no
/livez//readyz. The image contains only business routes; do not copy the probe paths from the other services — use TCP 3000 for the probe, or hitGET /api/config(dynamically rendered, which proves the Node process can still respond). Hitting/livezgives 404, the probe keeps failing, and the Pod restarts over and over.
Prerequisites: themis-auth (the OIDC IdP; the thia-web client must already be registered in its OIDC_CLIENTS),
thia-gateway, rhea-gateway.
Server-side variables (read server-side only, never delivered to the browser)
| Variable | Source | Required | Description | Placeholder/default |
|---|---|---|---|---|
PORT |
Literal | Yes | Next service port | 3000 |
SITE_DOMAIN |
ConfigMap | Yes | Primary public domain, used for canonical / hreflang / sitemap / robots / OG. Read once at process start; restart the Pod after changing it | titanides.com |
API_DOMAIN |
ConfigMap | Yes | Registered domains the frontend may connect to, used to generate the CSP connect-src; space- or comma-separated for several. Must be the gateway's public domain; otherwise CSP only reports and does not block |
titanides.com |
CONTACT_EMAIL |
ConfigMap | Optional | Footer contact | <address> |
DISCORD_URL |
ConfigMap | Optional | Discord invite link | <url> |
COMPANY_URL |
ConfigMap | Optional | Company / website link | <url> |
EXTENSION_STORE_URL |
ConfigMap | Optional | Chrome Web Store link; empty shows "coming soon" | <url> |
EXTENSION_PREVIEW_ZIP_URL |
ConfigMap | Optional | Extension preview package download address | <url> |
PLACEHOLDER_HOST |
ConfigMap | Optional | Full host that should show a notice (compared exactly against the Host header, no wildcards). Empty disables it | <host> |
PLACEHOLDER_NOTICE |
ConfigMap | Optional | The one-line notice shown on that host | <notice> |
THIA_OIDC_ISSUER |
ConfigMap | Yes | The IdP's issuer, e.g. https://accounts.titanides.com. If missing the process throws at startup |
https://accounts.titanides.com |
THIA_OIDC_CLIENT_ID |
ConfigMap | Yes | Public client, fixed to thia-web |
thia-web |
THIA_OIDC_REDIRECT_URI |
ConfigMap | Yes | https://titanides.com/api/auth/callback, must match what is registered in OIDC_CLIENTS |
https://<site>/api/auth/callback |
AUTH_FLOW_TOKEN |
Secret | Yes | HMAC key sealing the PKCE / state flow cookie. If unset in production, /api/auth/token returns 503 not_configured directly |
<random-string> |
AUTH_SESSION_TOKEN |
Secret | Yes | AES-256 key for the session cookie. Must be identical across replicas; rotating it signs everyone out | <random-string> |
AUTH_SESSION_TTL_SECONDS |
ConfigMap | Optional | Session lifetime in seconds; values below 60 are ignored | 604800 |
AUTH_FLOW_TTL_SECONDS |
ConfigMap | Optional | Time limit for the sign-in round trip, in seconds | 1800 |
Client variables (delivered via /api/config; the variable names are camelCase — do not change them to uppercase)
| Variable | Source | Required | Description | Placeholder/default |
|---|---|---|---|---|
endpoint |
ConfigMap | Yes | JSON for the main gateway. If missing, server-rendered data pages 500 outright | {"PROTOCOL":"https","HOST":"<gateway-host>","PORT":443} |
wsEndpoint |
ConfigMap | Yes | WebSocket address for the agent interaction stream; if missing, conversations cannot be sent | {"PROTOCOL":"ws","HOST":"<gateway-host>","PORT":443,"BASEPATH":"ws"} |
themisEndpoint |
ConfigMap | Yes | themis-gateway address; if missing, the profile area does not refresh | {"PROTOCOL":"https","HOST":"<themis-gateway-host>","PORT":443} |
rheaEndpoint |
ConfigMap | Yes | rhea-gateway address. The consequence of leaving it out is silent: balance and transactions show empty, and pricing falls back to built-in packages (no priceId, so subscription buttons stay disabled) |
{"PROTOCOL":"https","HOST":"<rhea-gateway-host>","PORT":443} |
rheaConsoleUrl |
ConfigMap | Optional | Billing console address; the wallet card on the user page links to it, and no link is rendered when empty | https://<rhea-console-host> |
agentVariantHeader |
ConfigMap | Optional | Request header name used for variant / canary routing; must match the VirtualService header match exactly | variant-<agent> |
defaultAgent |
ConfigMap | Optional | The code of the default agent; must exist in the agent catalog, leave empty to let the backend decide |
<agent-code> |
gaMeasurementId |
ConfigMap | Optional | GA4 measurement id (G-...); empty turns analytics off. Should only be set in production |
G-<id> |
googleClientId |
ConfigMap | Optional | Google OAuth client id, a public value; empty hides the Google sign-in button | <google-client-id> |
staticCdnUrl |
ConfigMap | Optional | Site static-asset CDN base (a full URL, no trailing slash); curated assets and 3D models use it too | <cdn-base-url> |
staticAssetVersion |
ConfigMap | Optional | Cache-busting suffix for static assets, used to force a refresh while the CDN cache is still valid | <version> |
ssoProviders |
ConfigMap | Optional | SSO entry array, JSON: [{"key":"<provider>","label":"<label>","logoUrl":"<url>"}]; key must match a provider registered in themis-auth |
[] |
⚠️ A failed JSON parse on
endpointis silent.getServerConfig()wrapsJSON.parsein an empty catch; one full-width comma and the key simply disappears — the process starts as usual, and the symptom is a 500 on data pages or a UI full of "—".
Verify: open the site → click sign in → sign in at accounts.titanides.com → return to this site and see your avatar;
create a session, send a message, and see a streaming reply.
Common mismatches (all manifest as "right after signing in you are back to signed out"): THIA_OIDC_REDIRECT_URI does not match the IdP registration,
or AUTH_SESSION_TOKEN differs between replicas.
A wrong SITE_DOMAIN / API_DOMAIN does not block sign-in — CSP is currently Report-Only; it records but does not block.
So you cannot use it as a safety net either: many CSP error logs do not mean there is no configuration problem.
Corresponding Bundle pack: app: thia-web
mcp-*
What it does: the tool services the agent calls while working; each is a standalone MCP server. Install as needed — which ones you install depends on which capabilities you want, and the five have no dependencies on each other. For the tools each service provides and how they are priced, see MCP tool services.
| Service | What it provides | External credentials |
|---|---|---|
mcp-vision |
Text-to-image, image editing, image blending (Seedream / Gemini) | At least one model key |
mcp-perception |
Image description, framing comparison | Ark key |
mcp-motion |
Text / image / reference-image to video (Seedance) | Ark key |
mcp-fetch |
Fetch web pages and RSS | None |
mcp-analysis |
Read-only SQL queries | Database connection string |
Manifest: each is one Deployment + ClusterIP Service (80 → 3000). All are stateless, with no PVC;
MCP_TRANSPORT=http is set by the image, and HTTP mode exposes only POST /mcp; it is sessionless by protocol
(each request creates a new server instance), so scaling replicas needs no sticky sessions.
⚠️ Not every one has a probe. Only
mcp-fetchandmcp-analysisprovideGET /health; the other three have no health route — use TCP 3000 for the probe.
⚠️ None of the five has inbound authentication. Anything that can connect can call it, so attach only a
ClusterIP; never expose it to the public internet or a same-domain Ingress.mcp-analysispermissions are enforced on the agent side: only sessions with theADMINrole can get this tool.
All five share MCP_TRANSPORT (fixed to http inside the cluster), PORT (3000), and LOG_LEVEL (written to stderr).
The tables below list every variable per service.
mcp-vision
| Variable | Source | Required | Description | Placeholder/default |
|---|---|---|---|---|
MCP_TRANSPORT |
Literal | Yes | Fixed to http inside the cluster; stdio is for local debugging only |
http |
PORT |
Literal | Yes | Service port | 3000 |
LOG_LEVEL |
ConfigMap | Optional | Log level | info |
SEEDREAM_ENDPOINT |
ConfigMap | Either one | Seedream model API base | https://<model-api>/api/v3 |
SEEDREAM_MODELS |
ConfigMap | Either one | Available Seedream models, comma-separated; empty disables this provider | <model-id> |
SEEDREAM_API_KEY |
Secret | Either one | Seedream key | <key> |
GEMINI_ENDPOINT |
ConfigMap | Optional | Gemini or self-hosted relay address | https://<gemini-endpoint> |
GEMINI_API_KEY |
Secret | Optional | Gemini key | <key> |
GEMINI_MODELS |
ConfigMap | Optional | Available Gemini models | <model-id> |
GEMINI_RELAY_TOKEN |
Secret | Optional | The relay's x-relay-token |
<token> |
DEFAULT_MODEL |
ConfigMap | With multiple models | Which model to use when the caller does not specify one; must resolve uniquely with several models | <model-id> |
RESPONSE_CONTENT_TYPE |
ConfigMap | Optional | Response shape: text / resource_link / image |
text |
STORAGE_* |
ConfigMap/Secret | Optional | The seven S3-compatible storage variables (AK / SK / region / endpoint / bucket / public URL / ACL); effective only when complete, and returns persistent URLs; otherwise the provider's temporary URL is used. How to fill them: Object storage and static assets | Same as mcp-motion |
mcp-perception
| Variable | Source | Required | Description | Placeholder/default |
|---|---|---|---|---|
MCP_TRANSPORT |
Literal | Yes | Fixed to http inside the cluster |
http |
PORT |
Literal | Yes | Service port | 3000 |
LOG_LEVEL |
ConfigMap | Optional | Log level | info |
ENDPOINT |
ConfigMap | Yes | Model service API base | https://<model-api>/api/v3 (Ark Beijing) |
MODEL |
ConfigMap | Yes | Default vision model id | doubao-seed-2-0-mini-260215 |
API_KEY |
Secret | Yes | Ark key. ⚠️ Not validated at startup; an empty value still starts, and the first call returns 401 | <key> |
RESPONSE_CONTENT_TYPE |
ConfigMap | Optional | Response shape | text |
THINKING_MODE |
ConfigMap | Optional | enabled / disabled / auto; description tasks usually set disabled to save latency |
Empty (model default; doubao defaults to on) |
mcp-motion
| Variable | Source | Required | Description | Placeholder/default |
|---|---|---|---|---|
MCP_TRANSPORT |
Literal | Yes | Fixed to http inside the cluster |
http |
PORT |
Literal | Yes | Service port | 3000 |
LOG_LEVEL |
ConfigMap | Optional | Log level | info |
ENDPOINT |
ConfigMap | Yes | Model service API base. ⚠️ Not validated at startup; the first call returns 401 | https://<model-api>/api/v3 |
MODEL |
ConfigMap | Yes | Default video model id; determines the capability table (which input combinations are available) | <model-id> |
API_KEY |
Secret | Yes | Model service key (can share one key with mcp-perception when they use the same source) | <key> |
RESPONSE_CONTENT_TYPE |
ConfigMap | Optional | Response shape: text or resource_link |
text |
POLLING_INTERVAL |
ConfigMap | Optional | Polling interval for generation jobs (milliseconds) | 10000 |
POLLING_TIMEOUT |
ConfigMap | Optional | Total polling timeout (milliseconds) | 300000 |
ARK_ASSET_* |
ConfigMap/Secret | Optional | Character asset library; enabled only when fully configured | <...> |
STORAGE_ACCESS_KEY_ID |
Secret | Optional | Object storage AK; without it the provider's temporary URL is used | <key> |
STORAGE_SECRET_ACCESS_KEY |
Secret | Optional | Object storage SK | <secret> |
STORAGE_REGION |
ConfigMap | Optional | Storage region | <region> |
STORAGE_ENDPOINT |
ConfigMap | Optional | S3-compatible upload endpoint | https://<s3-endpoint> |
STORAGE_BUCKET |
ConfigMap | Optional | Bucket name | <bucket> |
STORAGE_PUBLIC_URL |
ConfigMap | Optional | Public download prefix (CDN / custom domain) | <public-base-url> |
STORAGE_FORCE_PATH_STYLE |
ConfigMap | Optional | Set true for MinIO and other path-style backends |
false |
STORAGE_ACL |
ConfigMap | Optional | Object ACL; leave empty for Cloudflare R2 and similar. For all seven variables see Object storage and static assets | public-read |
mcp-fetch
| Variable | Source | Required | Description | Placeholder/default |
|---|---|---|---|---|
MCP_TRANSPORT |
Literal | Yes | Fixed to http inside the cluster |
http |
PORT |
Literal | Yes | Service port | 3000 |
LOG_LEVEL |
ConfigMap | Optional | Log level | info |
PER_HOST_RPM |
ConfigMap | Optional | Requests per minute per host; exceeding it waits rather than fails | 20 |
MAX_BYTES |
ConfigMap | Optional | Response body limit (bytes) | 2000000 |
TIMEOUT_MS |
ConfigMap | Optional | Single fetch timeout (milliseconds) | 20000 |
HTTPS_PROXY |
ConfigMap | Optional | Egress proxy. Must be set when the cluster cannot reach the internet directly, otherwise every fetch times out | <url> |
NO_PROXY |
ConfigMap | Optional | Addresses that bypass the proxy | <host>,<host> |
ALLOW_HOSTS / DENY_HOSTS |
ConfigMap | Optional | Host allow / deny lists; the deny list is checked first; empty means any public host | <host1>,<host2> |
USER_AGENT |
ConfigMap | Optional | User agent for fetch requests | <ua> |
The service always rejects loopback, private network, link-local, and cloud metadata addresses, regardless of the lists above.
mcp-analysis
| Variable | Source | Required | Description | Placeholder/default |
|---|---|---|---|---|
MCP_TRANSPORT |
Literal | Yes | Fixed to http inside the cluster |
http |
PORT |
Literal | Yes | Service port | 3000 |
LOG_LEVEL |
ConfigMap | Optional | Log level | info |
SERVER_NAME |
ConfigMap | Optional | MCP service identifier | <product>-mcp-analysis |
PG_DATABASES |
Secret | Yes | JSON array of queryable databases [{"id","label","url"}]; url must be postgres://. The connection string contains a password, so it must live in a Secret; if missing or malformed, the process throws at startup |
<json> |
MAX_ROWS |
ConfigMap | Optional | Row limit per query | 1000 |
STATEMENT_TIMEOUT_MS |
ConfigMap | Optional | Server-side statement timeout | 10000 |
QUERY_TIMEOUT_MS |
ConfigMap | Optional | Client query timeout (including streaming reads) | 15000 |
CONNECTION_TIMEOUT_MS |
ConfigMap | Optional | Connection timeout | 10000 |
POOL_MAX |
ConfigMap | Optional | Connection pool limit per database | 5 |
After deployment: register these services' addresses in thia-agent's configuration (see the thia-agent section at the top of this document), otherwise
the tools are not registered in the model's tool table — the service runs, but conversations can never call it.
thia-jobs-tick
It is not a Service but a Kubernetes CronJob: every 5 minutes it sends POST /api/v1/jobs/tick to the default variant of thia-agent
(no token and no key — it is designed as "trusted inside the cluster"). What actually runs is decided by the system;
the CronJob only knocks at the door on schedule.
| Requirement | Value | What happens if not met |
|---|---|---|
| Cadence | Every 5 minutes (*/5 * * * *), timeZone: Asia/Shanghai |
The shortest heartbeat interval is 5 minutes; a wrong time zone shifts "every day at 9" |
| Concurrency policy | concurrencyPolicy: Forbid |
A new tick starts before the previous one finished; the lease prevents duplicate execution, but you waste one run |
| Target | The default variant's Service: POST http://thia-agent/api/v1/jobs/tick |
Hitting a variant without jobs.enabled returns disabled, with no error |
| Variant config | Default variant jobs.enabled: true and routines.enabled: true |
With only the latter on and not the former, or vice versa, heartbeats silently do not run — the shipped agentic.yaml has no routines: section; it is off by default |
| Storage | store.driver: postgresql |
With SQLite or no database configured the job runtime does not start, leaving only one warning |
| Migrations | Run migrations such as 2026-09-add-scheduled-jobs.sql before creating the CronJob |
If the job table does not exist the job runtime shuts down degraded, /jobs/* returns disabled, and the process does not exit |
| Network | sidecar.istio.io/inject: "false"; the mesh is not STRICT mTLS |
With strict mutual TLS enabled, this CronJob without a sidecar cannot reach it, and heartbeats silently stop |
/jobs/tick returns 202 immediately by default; ?wait=true waits for the current round to finish before returning — use the latter during troubleshooting to see the real execution result.
Create only one for the whole cluster: do not create one per user or per job — thousands of users would mean thousands of cluster objects, and you would also have to hand out cluster API permissions. Cadence and "who is running" are recorded in job rows in the database; a single CronJob scanning the whole table is enough.
Tethys: DevOps (optional)
Without Tethys the whole system still runs. It solves a different problem: packaging applications into Bundles and publishing them to target clusters, and managing cluster resources, tenants, and microservice lifecycles in a UI — publish, upgrade, scale, roll back, and launch egress proxy and network diagnostic containers from the console.
It consists of three services; the other two common features (egress proxy, network diagnostics) are not always-on services — see the end of this section.
tethys-shipping
What it does: two processes, usually split into two Deployments.
- Shipping API: a REST interface that creates, reads, updates, and deletes Kubernetes-native resources, Istio resources, and FewBox CRDs, and wraps tenant, microservice lifecycle, job scheduling, and middleware installation.
- PackingTable operator: watches three CRDs —
Bundle,Infrastructure,Middleware— and reconciles them into Deployments / Services. Path A's Bundle deployment depends on it — "base layer installation" installs exactly this.TenantandRegistryhave no controller: the former is a record the console maintains, the latter is pre-installed on the platform side.
Prerequisites: a ServiceAccount with cluster-level permissions. The operator needs to create Deployments, Services, Ingresses,
ClusterRoles, and even CRDs; the permission list is in operator-role.yaml — it is inherently a privileged component and should only be installed in a controlled cluster.
① CRDs and operator
This is the step in "One-click deployment / PackingTable operator": the full text of all three manifests (ClusterRole, ClusterRoleBinding, Deployment) is there, not repeated here. The CRDs install themselves when the operator starts (transpiled from the entity types); there is nothing to apply for them.
② ServiceAccount
kubectl create namespace fewbox-system
kubectl create serviceaccount fewbox -n fewbox-system
③ Deploy the operator
kubectl apply -f deploy/deployment.yaml
kubectl get pods -n fewbox-system
The operator connects to the API Server via POD_NAMESPACE and DevOps__Endpoints__K8SEndpoint__*; inside the cluster use
kubernetes.default.svc, port 443, with credentials from the ServiceAccount token.
④ Deploy the Shipping API
Build the image from the repository root's Dockerfile (the operator uses the packingtable one). The container port is decided by PORT;
the image default is 8080 (.NET container convention), while the Service is still 80 externally — targetPort must match the port the container actually
listens on, while SHIPPING_ENDPOINT.port is filled with the Service port 80. You need:
| Variable | Source | Required | Description | Placeholder/default |
|---|---|---|---|---|
PORT |
Literal | Yes | Shipping port; PackingTable and the console build the Service port from it | 5000 (image default 8080) |
DevOps__Endpoints__K8SEndpoint__Host |
ConfigMap | Yes | Inside the cluster use kubernetes.default.svc; outside the cluster use the API Server address |
kubernetes.default.svc |
DevOps__Endpoints__K8SEndpoint__Port |
ConfigMap | Yes | API Server port | 443 |
DevOps__Endpoints__K8SEndpoint__AppSettingsToken |
Secret | Yes | ServiceAccount token | <token> |
Inside the cluster it uses the ServiceAccount to reach the apiserver, so no kubeconfig is needed; only when running Shipping
directly on a local machine do you fill in K8S_ENDPOINT / K8S_TOKEN in .env. Whichever cluster Shipping points at is the cluster the console manages.
To obtain the token:
kubectl create token fewbox --duration 8760h -n fewbox-system
Its data lives in a SQLite file. If you need to keep release history and tenant data, mount the directory containing that file onto a PVC; without that, Pod recreation loses it.
Verify: kubectl get crds | grep fewbox.com shows six CRDs (tenants, bundles, infrastructures,
middlewares, families, registries); both the operator and API Pods are
READY; the user list query works when called from the tethys-gateway side.
Corresponding Bundle pack: app: tethys-shipping
tethys-gateway
What it does: the console's GraphQL entry point — it translates management operations to the Shipping API, and performs JWT verification and CORS;
it also provides /stream (SSE) and WebSocket for the console to watch job output and logs.
Configuration
| Variable | Source | Required | Description | Placeholder/default |
|---|---|---|---|---|
PORT |
Literal | Yes | Gateway port; Service port 80 → container port | 3000 |
SHIPPING_ENDPOINT |
ConfigMap | Yes | host is the Service name (= the application name in the console), port is the Service port 80; for cross-namespace use <service>.<tenant>.svc.cluster.local |
{"protocol":"http","host":"tethys-shipping","port":80,"basePath":"api"} |
SHIPPINGWS_ENDPOINT |
ConfigMap | Required when using live lists | No basePath: /watch and /xterminal hang off Shipping's root path |
{"protocol":"http","host":"tethys-shipping","port":80} |
WS_PROXIES |
ConfigMap | Required when using live lists | See the JSON below. Each watch path must be listed individually; see the matching rules below | [{"name":"<name>","path":"ws","target":"ws://<svc>:8080"}] |
GRAPHQL_BODY_LIMIT |
ConfigMap | Optional | /graphql request body limit, express.json syntax (e.g. 10mb, 512kb). Bundle import stuffs a whole YAML into one GraphQL variable, so the default is already relaxed to 10mb |
10mb |
JWT_VERIFY_ALGORITHM |
ConfigMap | Yes | Only ES256 is accepted. Any other value fails at startup; there is no HS256 / JWT_SECRET fallback |
ES256 |
JWT_PUBLIC_KEY |
Secret | Yes | themis signing public key PEM; supports a single-line literal with \n; use one of the two with the next row |
<pem> |
JWT_PUBLIC_KEY_PATH |
Secret (file) | Yes | Points to a mounted Secret file; when both are configured the file wins | <path> |
CORS |
ConfigMap | Yes | JSON array. The browser connects to the gateway directly, so the Origin must match exactly | ["https://console.titanides.com"] |
PERMISSIONS_OPEN |
ConfigMap | Optional | Temporarily skips JWT verification and ADMIN authorization; use only while the identity service is not yet wired up. The log prints a [SECURITY] warning; do not leave it in production |
false |
SUPABASE |
Secret | Yes | The console's user table currently lives in Supabase | {"url":"https://<project>.supabase.co","key":"<anon key>"} |
The public key must be the one the identity service currently signs with. When missing, the process fails at startup (startup self-check); conversely, if the gateway starts but every GraphQL field returns
Access Denied: ..., the public key exists but is not the identity service's current one — common when the identity service has rotated its signing key (the JWKSkidchanges). Take the public key from the EC P-256 key inhttps://accounts.titanides.com/jwks: concatenate the JWK'sxandyas04 || x || y, wrap it in an EC SubjectPublicKeyInfo, and base64 it into PEM.
Every GraphQL root field is
and(isAuthenticated, isAdmin); outsidePERMISSIONS_OPENthere are no public read-only fields. When the account has noADMINrole it returnsAccess Denied: ADMIN role required; the UI shows a message and stops, without redirect loops.
The full WS_PROXIES value (the public path defaults to /<lowercased endpoint>/<path>, i.e. /shippingws/...):
[
{"endpoint":"SHIPPINGWS","path":"watch/api/v1/namespaces"},
{"endpoint":"SHIPPINGWS","path":"watch/apis/apps/v1/deployments"},
{"endpoint":"SHIPPINGWS","path":"watch/api/v1/pods"},
{"endpoint":"SHIPPINGWS","path":"watch/apis/batch/v1/jobs"},
{"endpoint":"SHIPPINGWS","path":"watch/apis/batch/v1/cronjobs"},
{"endpoint":"SHIPPINGWS","path":"xterminal"}
]
Matching is an exact comparison of the whole pathname, with no prefix matching. Leave one out and only that one WebSocket breaks while everything else works — the symptom is one list not refreshing.
tethys-web'swsEndpoint.BASEPATHmust equal the public prefix here (shippingws).
⚠️
SUPABASEis a Tethys legacy — it predates unified identity, and its user table is separate informuser. Once themis is integrated this item will be removed; until then, a private deployment must prepare an extra Supabase instance. If you do not want to bring it in, you can also skip Tethys for now — the core product does not depend on it.
Deploy: Deployment + ClusterIP Service (80 → 3000), probes /livez, /readyz.
Verify: /livez returns {"status":"ok"}; a preflight with an Origin returns 204 with
Access-Control-Allow-Origin: https://console.titanides.com; querying a root field without a token should return
Access Denied: Authentication required (which shows authentication is in effect, not bypassed by PERMISSIONS_OPEN).
Corresponding Bundle pack: app: tethys-gateway
tethys-web
What it does: the cluster management console — cluster overview, namespaces and workloads, Bundles and CRDs, tenants, microservice lifecycles, storage, logs, and a terminal.
Configuration
| Variable | Source | Required | Description | Placeholder/default |
|---|---|---|---|---|
PORT |
Literal | Yes | Next service port; Service port 80 → container port | 3000 |
endpoint |
ConfigMap | Yes | Gateway GraphQL/SSE address, JSON. Public address — the browser uses it for GraphQL; a Service name will not resolve there | {"PROTOCOL":"https","HOST":"console.titanides.com","PORT":443} |
wsEndpoint |
ConfigMap | Yes | Gateway WebSocket address, JSON. BASEPATH must equal the public path prefix of tethys-gateway's SHIPPINGWS |
{"PROTOCOL":"wss","HOST":"console.titanides.com","PORT":443,"BASEPATH":"shippingws"} |
TETHYS_OIDC_ISSUER |
ConfigMap | Yes | The identity service's public issuer, no trailing slash; must match themis-auth's OIDC_ISSUER exactly |
https://accounts.titanides.com |
TETHYS_OIDC_CLIENT_ID |
ConfigMap | Yes | This application's client_id in OIDC_CLIENTS |
tethys-web |
TETHYS_OIDC_REDIRECT_URI |
ConfigMap | Yes | Authorization-code callback address; must match OIDC_CLIENTS's redirect_uris exactly |
https://console.titanides.com/api/auth/callback |
AUTH_FLOW_TOKEN |
Secret | Yes | Sealing key for the sign-in flow cookie (state / nonce / PKCE verifier). No default in production; if missing, sign-in reports a configuration error directly | <random-string> |
AUTH_SESSION_TOKEN |
Secret | Yes | Encryption key for the session cookie (tethys_session). It is generated separately from the previous one and must not be shared; likewise no default in production |
<random-string> |
TETHYS_OIDC_LOGOUT_ENDPOINT |
ConfigMap | Optional | Sign-out address, default ${TETHYS_OIDC_ISSUER}/logout (i.e. the end_session_endpoint in auth discovery). Override only if the gateway's external sign-out path differs |
${TETHYS_OIDC_ISSUER}/logout |
TETHYS_OIDC_AUTHORIZATION_ENDPOINT |
ConfigMap | Optional | Defaults to ${TETHYS_OIDC_ISSUER}/authorize; usually no need to fill it |
— |
TETHYS_OIDC_TOKEN_ENDPOINT |
ConfigMap | Optional | Defaults to ${TETHYS_OIDC_ISSUER}/token; usually no need to fill it |
— |
TETHYS_OIDC_SIGNOUT_ENDPOINT |
ConfigMap | Optional | Defaults to ${TETHYS_OIDC_ISSUER}/api/v1/signout; usually no need to fill it |
— |
AUTH_FLOW_TTL_SECONDS |
ConfigMap | Optional | Flow cookie lifetime (seconds); values below 60 are ignored | 1800 |
AUTH_SESSION_TTL_SECONDS |
ConfigMap | Optional | Session sliding lifetime (seconds); align it with the identity service's REFRESH_TOKEN_EXPIRES_IN |
604800 |
endpoint/wsEndpointare JSON strings that start with a lowercase letter; the browser reads them from this service's/api/config— it passes through verbatim every environment variable key ending inEndpoint(plus the lowercaseendpoint), and matching is case-sensitive. WritingTETHYS_ENDPOINTwill not match and the frontend reads nothing. The otherTETHYS_OIDC_*/AUTH_*are read server-side only and will not appear in/api/config.
Multiple replicas must share the same values.
AUTH_FLOW_TOKENandAUTH_SESSION_TOKENmust be identical on every replica: a cookie is issued by any replica, and the request may land on another one. When they differ the symptom is "sometimes you can sign in, sometimes you cannot" — the session cookie cannot be decoded, and/api/auth/tokenreturns 401 directly.
TETHYS_OIDC_* are all server-side only (uppercase); the browser only sees the same-origin /api/auth/*:
- Sign-in: the browser goes to
${issuer}/authorize(with the PKCEcode_challenge), the authorization code returns toTETHYS_OIDC_REDIRECT_URI, and the server exchanges it for tokens at/token. The refresh token, id_token, and cached access token are written only into an encrypted HttpOnly cookie; only the access token is kept in browser memory, never in localStorage. If you are already signed in at the IdP it is a silent 302 with no login page. - Renewal: when the access token nears expiry, the browser calls the same-origin
POST /api/auth/token; the server exchanges the refresh token in the cookie for a new one (refresh tokens rotate), and re-seals the new tokens into the cookie. - Sign-out: first call the local
/api/auth/signoutto delete the refresh token, blacklist the access token'sjti, and clear the session cookie; then navigate the full page toTETHYS_OIDC_LOGOUT_ENDPOINTto clear the IdP session, and finally return to an address registered inpost_logout_redirect_uris— fixed to the site root, not the page you were on before signing out. - The console receives tokens issued by themis, so
tethys-gatewaymust be configured with the same public key (see the previous section).
Three things to change together before deploying (if any one is mismatched the symptom is that you cannot sign in, not a configuration error):
- Register this application in the identity service's
OIDC_CLIENTS;redirect_urisandTETHYS_OIDC_REDIRECT_URImust match exactly (trailing slash, http vs https — nothing may differ), and registerpost_logout_redirect_uris. Client configuration is cached in-process; restart the identity service after changing it. - Add the console's Origin to
tethys-gateway'sCORS(e.g.["https://console.titanides.com"]), otherwise every browser request is blocked. - The console domain must really serve https: when
TETHYS_OIDC_REDIRECT_URIishttps://the session cookie isSecure, and if the edge actually serves http, sign-in keeps returning to signed out.
Deploy: Deployment + Service (80 → 3000); point the console domain at it at the edge.
Verify: after signing in the cluster overview and namespace list load; refreshing the page keeps you signed in (no login prompt again); clicking sign out should return to the site root, and signing in again should require input (no silent SSO straight through). If sign-in succeeds but keeps bouncing back to the login page, see "Login succeeds but you are sent back to the login page forever" in "Troubleshooting".
Corresponding Bundle pack: app: tethys-web
Egress proxy and network diagnostics (launched from the console)
The following two are not preinstalled Deployments but two one-click presets on the console's "Manage microservices" page: they come with
tethys-web once it is installed; there is no separate manifest to apply.
Egress proxy
Lets services in the cluster reach LLM providers and image registries through a fixed egress, suited to target clusters that cannot connect overseas directly.
- Default image
metacubex/mihomo:latest, start command/mihomo -d /etc/mihomo - Port
7897; configuration mounted asconfig.yamlat/etc/mihomo - Started with
isRawNetwork— outside the service mesh, otherwise the proxy itself would be taken over by the mesh
⚠️ The template ships with a sample VLESS node; you must replace server and uuid with your own egress configuration — do not copy it.
After it starts, point HTTP_PROXY / HTTPS_PROXY of the services that need the proxy (for example thia-agent, if it must reach overseas models) at that Service.
Network diagnostics
One click starts a nicolaka/netshoot container (sleep infinity); in the console terminal run curl,
ping, nslookup, traceroute directly to troubleshoot connectivity, DNS, and mesh problems. Delete it when done; it does not stay running.