Deploy with Helm
Tara and Ryoma run on Kubernetes, and each service has a Helm chart in its own repo. This page covers the infrastructure to prepare, the Helm values you usually set, the install order, and how to verify after installing. Bandum isn't covered here because it runs locally on the user's machine, and neither Tara nor Ryoma ever calls into Bandum.
Swipe sideways to see the whole diagram.
Required infrastructure
The chart only references the components below and doesn't install them, so set them up first.
| Component | Used for | Notes |
|---|---|---|
| Kubernetes 1.27 or later, an Ingress controller, cert-manager or an existing certificate | Tara, Ryoma | Claude Code downloads packages only over HTTPS, so Tara needs a certificate that users' machines trust |
| PostgreSQL 17, one database per service | Tara, Ryoma | Tara treats this as the source of truth for versions, roles, and audit |
| S3 or MinIO, with a pre-created bucket and versioning turned on | Tara | The access key has permissions only on that bucket |
| Vault or OpenBao with Transit and an Ed25519 key | Tara | Holds the package signing key, in place of a key file |
| ClickHouse 26.x | Ryoma | Native port. Needs one write user for the Collector and two read-only users for Grafana |
| Your organization's private registry | Tara, Ryoma | Holds the tara-api, tara-portal, and ryoma-api images |
| Internal network or VPN | Grafana | Don't expose Grafana to the Internet |
| ClamAV | Tara | Optional. The chart includes it, and you turn it on with clamav.enabled |
You need three domain names. Tara uses a single host for both the Portal and the API, for example tara.phillipcli.cloud. Ryoma has its own host to receive telemetry, for example ryoma.phillipcli.cloud. Grafana has an internal host.
Build images
Tara builds two images from the same Dockerfile, and Ryoma builds one image and needs Bandum's shared code.
docker build --target api --build-arg VERSION=0.1.0 -t <registry>/tara/tara-api:0.1.0 Tara
docker build --target portal -t <registry>/tara/tara-portal:0.1.0 Tara
docker build --build-context bandum-pkg=Bandum/pkg -t <registry>/ryoma/ryoma-api:0.1.0 RyomaCommon Helm values
Each chart has a complete, commented values.yaml, plus values-staging.yaml and values-production.yaml. You override them with a separate file for your own environment. This file must not contain secrets, because secrets live in an existing Secret that the chart references through secrets.existingSecret.
The key values for Tara are:
| Value | Meaning |
|---|---|
image.api.*, image.portal.* | Images and tags |
ingress.host, ingress.tls.secretName | Tara's single host. TARA_PUBLIC_URL and TARA_PORTAL_URL are derived from it |
s3.endpoint, s3.bucket, s3.region, s3.pathStyle | The package store. The access key lives in the Secret |
signing.vault.addr, .mount, .key | The signing key in Transit. The Vault token lives in the Secret as TARA_SIGNING_VAULT_TOKEN |
worker.mode | embedded runs the worker in the same process as the API, suitable for staging. separate splits the worker into its own Deployment, recommended for production |
clamav.enabled | Turns on malware scanning |
config.* | The rest of the non-secret TARA_* variables, such as ryomaUrl, grafanaUrl, apps |
secrets.existingSecret | Name of the existing Secret that holds the secret keys |
migration.seedConfig | true (default): the migration Job also runs tara-admin seed-config, which creates the organizations and loads the model catalog. It is idempotent |
migration.existingSecret | A second Secret that only the migration Job reads: TARA_MIGRATE_DATABASE_URL (the database owner) and TARA_APP_DB_PASSWORD (the password of the role tara_app). Required with secrets.existingSecret |
config.env | production (default): the API and the worker refuse to start when their database role is a superuser or has BYPASSRLS |
config.singleOrg, config.githubOrg | Only for a self-hosted install with one organization: its slug, and optionally the GitHub organization whose members join it at sign-in. Empty is the multi-organization (SaaS) mode, where anyone can sign in and create or join organizations. See Self-hosted, single organization |
Database roles. Tara isolates organizations with PostgreSQL row-level security, which a superuser bypasses. TARA_DATABASE_URL in Tara's Secret must therefore connect as the role tara_app (no superuser, no BYPASSRLS), and the migration Job, which connects as the database owner through migration.existingSecret, creates or updates that role on every run and grants it on all tables, including default privileges for tables created later. The API and the worker never see the owner credentials.
Tara's Secret needs at least TARA_DATABASE_URL, TARA_S3_ACCESS_KEY, TARA_S3_SECRET_KEY, and TARA_SIGNING_VAULT_TOKEN. Depending on how users sign in, add TARA_GITLAB_PROVIDERS or TARA_GITHUB_CLIENT_SECRET, and TARA_OAUTH_CLIENTS for web apps such as Grafana. TARA_DELEGATION_KEY (a random secret of at least 32 characters, openssl rand -hex 32) lets the Portal read project data from Ryoma on behalf of the signed-in user: Tara signs a short-lived, read-only token bound to that user and organization. Only tara-api holds this key; never reuse it as a Ryoma or Bandum credential. For how to register OAuth apps and get these values, see Prepare GitHub and GitLab.
The key values for Ryoma are:
| Value | Meaning |
|---|---|
api.ingress.host | The address Phillip sends telemetry to, that is PHILLIP_RYOMA_URL |
config.taraUrl, config.taraKeys | Tara issues identities to Ryoma, along with Tara's public key |
collector.clickhouseEndpoint, collector.rawTTL | ClickHouse and how long to keep raw logs |
clickhouse.*, postgres.* | Datasources for Grafana |
grafana.rootUrl, grafana.oauth.* | The Grafana address and sign-in through Tara |
grafana.ingress.enabled | Off by default. Turn it on only with an internal or VPN IngressClass |
api.replicas | Number of ryoma-api replicas, 2 by default in production |
config.scmPlugin | The GitHub scm kit for Ryoma (RYOMA_SCM_PLUGIN), as name@version:sha256. Get the sha256 on the resource page on Tara |
config.scmGitlabPlugin | The GitLab scm kit (RYOMA_SCM_GITLAB_PLUGIN), as kit-scm-gitlab@<version>:<sha256>. Default empty, which means GitLab repositories aren't read. It needs config.scmPlugin and the RYOMA_TARA_SCM_TOKEN key in Ryoma's Secret, and a project must list its repository as a URL (https://host/group/name) |
config.scmServerTokenOrgs | Deprecated. Slugs of organizations that may use the server's own read-only SCM token for tasks and PRs. Default empty. It is only a fallback for single-organization or GitLab installs, and an organization with a GitHub App never uses it. See the Self-hosting reference |
Ryoma's Secret needs RYOMA_DATABASE_URL, RYOMA_CLICKHOUSE_URL, RYOMA_TARA_TOKEN, the ClickHouse credentials, and the Grafana password. Grafana is for operators only. See Grafana for operators.
Run multiple ryoma-api replicas
When api.replicas is greater than 1, every replica receives telemetry and webhooks. The background loops, such as quota evaluation, task copying, the weekly digest, and precomputing metrics for Grafana, run only on the one replica that holds the leader lock in PostgreSQL. If the leader dies, the lock releases on its own and another replica takes over after at most config.leaderRetry, 15 seconds by default.
You need no infrastructure beyond the PostgreSQL you already use. Each replica holds one extra connection of its own, so account for it in max_connections. If you put PgBouncer in between, use session mode or connect directly for RYOMA_DATABASE_URL, because a session-level lock doesn't survive transaction pooling. To split out a dedicated worker, run an extra Deployment from the same chart and image, and set RYOMA_BACKGROUND=off on the HTTP replicas.
Install order
This order matters because Ryoma needs Tara to have already released the tools and issued a token.
Prepare the external infrastructure: two PostgreSQL databases, the S3 bucket, the Transit key, ClickHouse, DNS, certificates, and the Secrets for both charts.
On ClickHouse, create the
oteldatabase, the write user for the Collector, and the two read-only users for Grafana with the sample files inRyoma/deploy/clickhouse/, or the equivalent SQL commands.Install Tara:
bashhelm upgrade --install tara Tara/deploy/helm/tara -n tara -f values-production.yaml -f custom.yamlThe migration job runs before the API changes version. If the migration fails, the old version keeps running.
Make an account that has already signed in the first owner (
tara-admin grant <login> <org> owner) and, for your own team, create admin console staff accounts (tara-admin staff create <login> --role moderator --email <email>; customer accounts have no platform flag). Then get Tara's public key fromGET /v1/signing-keysand put it in the Ryoma and Phillip configuration.Release Phillip and the tools to Tara with
tara-admin phillip-releaseandtara-admin tool-release. Then create a read-only Tara token for Ryoma withph tara tokens create ryomaand put it in Ryoma's Secret.Install Ryoma with
helm upgrade --install ryoma Ryoma/deploy/helm/ryoma -n ryoma -f ....ryoma-apimigrates PostgreSQL and ClickHouse on its own. The Collector creates theotel_logstable, so theryoma-apipod has a generous startupProbe to wait for the Collector to come up first.Create the read-only Grafana user on PostgreSQL with the file
Ryoma/deploy/postgres/grafana-user.sql.Register the
grafanaclient in Tara'sTARA_OAUTH_CLIENTS, then upgrade Tara. Thegrafana-initjob already built the org and dashboards when you installed Ryoma.
If you already have packages in a local directory, the command tara-admin artifacts-copy <directory> --dry-run previews the copy to S3. Remove --dry-run to copy for real and verify the sha256.
Ingress and the documentation sites
Tara's Ingress uses a single host for both the Portal and the API. Paths that the API handles, such as /v1, /auth, /oauth, /claude, /phillip, /tools, /install.sh, and /healthz, go to the API, and everything else goes to the Portal. Because they share an origin, the session cookie works without CORS. The Ingress must allow bodies up to 220 MB because a package can be up to 200 MiB.
PhillipCLI publishes two static sites, built from one VitePress project. Neither is part of the Portal, and neither exposes the API or the Portal. Both can be public even when Tara sits behind a VPN.
- The documentation site is for customers. The chart deploys it as a separate component (
docs.enabled, image targetdocs-web) with its own Ingress ondocs.host(defaultphillipcli.cloud). Self-hosters build it withDOCS_TARA_URL(the Tara address shown in articles),DOCS_URLandDOCS_DEVELOP_URL(the developer site it links to), and point the Portal at it with theDOCS_URLbuild argument. The status page calls Tara from the browser, so Tara's/healthzand/phillip/latest.jsonmust allow the docs origin through CORS. - The developer site is the one you are reading (
develop.enabled, image targetdevelop-web, hostdevelop.host, defaultdevelopers.phillipcli.cloud). Build it withDOCS_PUBLIC_URL(the documentation site it links back to). Its Internal section is for admin console staff only: setdevelop.internal.enabled=true(it needsadmin.enabled=true: readers sign in at the admin console with a staff account) and putTARA_DOCS_INTERNAL_KEY(at least 32 random characters) in the Secret. Without them the Internal section stays closed to everyone. Its nginx reaches the API inside the cluster (develop.taraInternalUrl, by default the API Service of the release) to check a sign-in ticket.
Old tara.<host>/docs links are redirected only by the single-host Caddy, not by this chart.
Backup
Have a backup plan for each kind of data and periodically test restoring into a staging environment.
| Data | How to back up |
|---|---|
| Tara's PostgreSQL | pg_dump or a snapshot with WAL. This is the source of truth for versions, roles, and audit |
| S3 bucket | Turn on versioning, and object lock or replication if available. Packages are immutable, so the bucket is almost append-only |
| Signing key | Lives in Transit. Back it up following the Vault or OpenBao procedure. If you lose the key, you must re-sign every package with tara-admin sign-published --resign |
| Ryoma's PostgreSQL | Back up the same way as Tara's |
| ClickHouse | clickhouse-backup or a volume snapshot. Raw data expires on its own according to collector.rawTTL |
| Grafana | Snapshot the PVC or use an external database. You can rebuild dashboards from the chart |
Verify after installing
Verify in order from easiest to hardest.
- Run
helm lintandhelm templatefor both charts. - Call
https://tara.phillipcli.cloud/healthz, which also checks PostgreSQL. Also call/install.shto make sure the install script comes out correctly. - Release a sample resource, then check that the package is in the bucket and the sha256 matches.
- From a real user machine, run
ph setupand thenph tara install <resource>. Claude Code must download the package over HTTPS on its own, with the authentication header, and verify the sha256. - Point
PHILLIP_RYOMA_URLat Ryoma and runph forge doctor. Theryoma-apilog must show the user and organization, and the Grafana dashboards must show data. - Sign in to Grafana through Tara from the internal network with Grafana's own admin account (Tara no longer grants Grafana Admin to customer accounts). From outside the VPN, you can't get in, and customers don't use Grafana.
Upgrade
Upgrade with the same helm upgrade --install command and a new image tag. On the Tara side, the migration job runs before the API changes version, so if the migration fails, the release stops and the running version isn't affected. On the Ryoma side, ryoma-api migrates on startup. Before each major upgrade, make sure the latest PostgreSQL backup is usable.