Private deployment overview
Dependencies between services, the trade-off between the two deployment paths, and the cluster and network prerequisites. Read on once you have decided to install.
Components and dependencies
An installation is 19 Services plus one scheduled job (see Services and ports for each one). The call shape between them is very regular:
every line is three tiers internally — web → gateway → backend — so you only need to know the nine edges that cross lines. When a connection is wired wrong, the problem is always there.
The table below lists only the edges and what breaks, not the variables: which variable wires each edge is in
References between variables, and each variable's source and default
are in the matching section of Path B: manual per-service deployment.
| Caller | Callee | What happens if it breaks |
|---|---|---|
thia-gateway |
themis-auth |
Users and roles cannot be resolved, and authentication fails across the whole console |
rhea-gateway |
themis-auth |
The organization wallet will not open (organization membership cannot be read) |
phoebe-gateway |
themis-auth |
The user directory and acquisition statistics are empty |
themis-auth |
rhea-payment |
The signup bonus is not granted; signup itself is unaffected |
themis-auth |
rhea-email |
Verification, reset and invitation emails cannot be sent |
themis-auth |
rhea-push |
Alerts cannot be pushed out (only enabled when ALERT_WEBHOOK_URL is also configured) |
thia-gateway |
rhea-payment |
Stripe callbacks cannot come in, so top-ups never arrive |
phoebe-gateway |
thia-agent |
Usage and call statistics are empty |
phoebe-gateway |
rhea-payment |
Credit statistics are empty |
At the product-line level, it comes down to this, which directly answers the most common question — can I install only part of it:
- Rhea and Themis are a pair of base layers; install them together. Themis borrows Rhea to send verification emails and signup bonuses, and Rhea borrows Themis's organization information — neither direction reports an error; emails simply are not sent and the organization wallet is simply unavailable. Install these two completely before installing Theia.
- Themis is the only login entry point: every console authenticates through it, so swapping the IdP means swapping the login of every console.
- Tethys is optional; install it only when you need private packaging and release, and the cluster management console.
- Theia can be trimmed internally; the tool services (
mcp-*) are installed as needed and do not affect the main body. - Phoebe is entirely read-only; remove it and the other lines keep running.
In other words, you can start with the smallest set and add to it later as needed; you do not have to install everything at once.
Scheduled jobs (required)
A class of work in the system happens in the background on a rhythm: heartbeat checks, memory consolidation and de-duplication, credit settlement and posting. They are triggered by one scheduled job. Without it the system still installs and the pages still open, but these three things never happen — and the failure is silent, so afterwards it is easily mistaken for "the feature was never built".
It does not travel with the Bundle — an exported Bundle has no scheduledTaskPacks, so it is applied
separately, right after the Bundle (in the agent repository: k8s/thia-jobs-tick.yaml, one ConfigMap plus
one CronJob). Both deployment paths are covered in
"One-click deployment / scheduled jobs" and in the
thia-jobs-tick section of "Path B".
The two deployment paths
Every
<>in this documentation is a placeholder; replace it with the real value in your environment. Domains are always written astitanides.comand its subdomains; they are all made up, so substitute your own. This documentation never contains our internal addresses, credentials or example keys — if the copy in your hands does, you have the wrong copy.
The same system can be installed into a cluster in two ways, and the outputs of the two must be equivalent. Which one you choose depends on the situation, not on features:
| Path A: one-click Bundle deployment | Path B: manual per-service deployment | |
|---|---|---|
| Suitable for | First installation, day-to-day upgrades | Troubleshooting, customization, security audit |
| Amount of work | One YAML file | One manifest per service |
| What you can change when something breaks | Bundle fields | Any single place |
| What it asks of the customer | Knows kubectl apply |
Can read Deployment manifests |
Use A day to day; use B when something is wrong. Every step in "Path B: manual per-service deployment" notes which pack it corresponds to in the Bundle, so the two paths can cross-check each other.
Path B is not a "fallback". It is the expanded view of Path A — each
packin the Bundle expands into one Deployment. Writing B in turn exposes what A's spec is missing.
Bootstrap: in-cluster or out-of-cluster
The two paths above answer "what to install". There is a second, independent axis — "who calls the Kubernetes API" — and it combines with Path A into two ways of landing:
| Bootstrap | How | When |
|---|---|---|
In-cluster kubectl apply |
Walk the three base-layer steps in one-click deployment, then apply the Bundle | The default. Reproducible, fewest failure points |
| A local tethys | Run the three tethys services on your machine against the cluster, then create the operator, add the tenant and import the Bundle in the UI | You would rather not write YAML, or you are installing remotely for a customer; see out-of-cluster bootstrap |
Path B is not in this table: manual per-service deployment is kubectl work by definition, with no UI form.
All three landings (in-cluster Bundle / Bundle imported in the UI / per-service) produce the same objects; what differs is who executes them and how many credentials are in play.
Prerequisites
Before installing, confirm that the following are ready. Most of them are infrastructure your cluster already has, and you do not need to procure anything separately for us; the only things that genuinely need to be applied for in advance are one root domain (its subdomains are enough) and the corresponding certificates.
| Item | Requirement | Notes |
|---|---|---|
| Kubernetes | Measured v1.33 (MicroK8s); older versions see the warning below | Building from scratch: Cluster setup |
| Istio | Measured 1.30.2 | Requires Gateway + VirtualService, see Install Istio |
| PostgreSQL | A single instance, isolated by schema; must have pgvector |
All services share one database; it is not split per service, see Configure PostgreSQL |
| Domains | One root domain is enough; subdomains need no extra registration | Identity on accounts.titanides.com, gateway on gateway.titanides.com, console on console.titanides.com; subdomains of one root are same-site, so cookies and SSO never run into cross-site restrictions |
| TLS certificates | One per domain above | Termination inside or outside the cluster both work |
| Image registry | Can pull our images | A private registry requires an imagePullSecret |
| Object storage (optional) | Any S3-compatible storage; our production uses Cloudflare R2 | Durable links for generated images / videos and for site assets. Optional: without it, results fall back to the model provider's temporary URLs and showcase sections degrade — see Object storage and static assets |
⚠️ The supported range of Kubernetes versions is based on actual testing, not inference. The client library the deployment operator is compiled against is older than our reference environment, and we will not commit to cross-version compatibility on inference alone. Before signing, we will perform a complete Bundle deployment on a cluster of your target version, and then write the supported range into the delivery documentation.
Network requirements
thia-gatewayandthemis-gatewaymust be reachable from outside.themis-authmust not be exposed outside the cluster. When the browser performs OIDC, it hitsthemis-gateway's/authorize,/token,/jwksand/.well-known/openid-configuration, which the gateway proxies to it; all other calls (thia-gateway,rhea-gateway,phoebe-gateway) connect directly inside the cluster.- All inter-service traffic goes through Kubernetes Services without TLS (relying on Istio mTLS, if enabled).
Port convention
The convention common to all Services is port 80 → targetPort = the container's actual port. The Istio routing
also uses Service port 80, not the container port. This is the easiest place to get wrong when writing your own manifests.
For each service (including container port, probe paths, and whether it needs the public network), see Services and ports.
That document also covers this: probe paths are not uniform — some are at the root path, some under /api/v1, and the Next.js sites have none at all.
Domains, certificates and CDN
Three things on the public access path are easily conflated: DNS records, the TLS termination point, and the service bound to the hostname. They can be configured separately; when you change one, confirm the other two did not change with it.
- A hostname can only be bound to one service. Bind
gateway.titanides.comto two gateways at once, and the later binding wins while the other path silently returns 404. The symptom is deceptive: under the same domain/api/v1/...returns data while/graphqlreturns 404, and the preflight returns 204 but withoutAccess-Control-Allow-Origin— it looks like a CORS misconfiguration, but in fact the requests are hitting a different service. - Addresses read by the browser must be public addresses. Addresses used for calls between services take the Service name, but addresses delivered
to the browser (such as
tethys-web'sendpoint/wsEndpoint) must behttps://console.titanides.com; a Service name does not resolve in the user's browser. - TLS is usually terminated outside the cluster. nginx or the load balancer holds the certificate and can go back to the origin in plaintext or re-encrypted; the certificate is renewed at that layer, and the cluster needs to know nothing about it. The full configuration for building that layer yourself (WebSocket, upload limits, timeouts) is in Edge nginx.
If you put a CDN in front (Cloudflare orange-cloud, for example; step-by-step configuration in Cloudflare in front), browser-to-edge and edge-to-origin are two independent TLS segments: the browser sees the CDN's own certificate, and when going back to the origin the CDN acts as a client validating the certificate and does not replace the origin's certificate.
- Choose Full (strict) for origin encryption: the origin certificate's domain, validity period and chain must all pass validation. Point the edge configuration at
fullchain.pemrather thancert.pem— a CDN does not fetch intermediate certificates automatically the way a browser does. - The client IP seen by the origin becomes the CDN's address ranges. When you need the real IP, enable
real_ip_headerat the edge (CF-Connecting-IPfor Cloudflare) and trust the official ranges; otherwise logs, rate limiting and any per-IP troubleshooting all become useless. - The free plan caps a single request body at 100 MB; if you have large-file upload endpoints, test once up front, otherwise you will only see the 413 when a user uploads.
- Certificate renewal (HTTP-01) comes from the CDN edge back to the origin at
/.well-known/acme-challenge/; as long as that path is not blocked by a rule and is not forcibly redirected elsewhere, it passes as usual. After switching, runcertbot renew --dry-runonce. - After the switch, authoritative DNS takes effect within seconds; the rest depends on the TTL of the old records: a TTL of 300 means at most 5 minutes, and the browser's own DNS cache may add a few more minutes.