Skip to content

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.

Online deployment diagram. The Ingress accepts two hosts. The Tara host routes to the Portal, the Tara API and the worker. The Tara API uses PostgreSQL, S3 or MinIO storage, and Vault or OpenBao. The Ryoma host routes to the Ryoma API. The Ryoma API passes telemetry to the Collector, the Collector writes to ClickHouse, and Grafana reads from ClickHouse. The developer site is a separate static site on its own host.IngressPortal and Tara API share one host; the developer site has its own hostTaraPortalwebTara APIlibrary, reviewWorkerbackground jobsPostgreSQLsource of truthS3 / MinIOpackage storeVault / OpenBaosigning keysRyomaRyoma APIingest, authCollectorfilters dataGrafanadashboardsClickHouseraw metricsand counterstara.phillipcli.cloudryoma.phillipcli.cloud

Swipe sideways to see the whole diagram.

You set up the base infrastructure (PostgreSQL, S3, Vault and ClickHouse) first. The Helm chart only references it.

Required infrastructure ​

The chart only references the components below and doesn't install them, so set them up first.

ComponentUsed forNotes
Kubernetes 1.27 or later, an Ingress controller, cert-manager or an existing certificateTara, RyomaClaude Code downloads packages only over HTTPS, so Tara needs a certificate that users' machines trust
PostgreSQL 17, one database per serviceTara, RyomaTara treats this as the source of truth for versions, roles, and audit
S3 or MinIO, with a pre-created bucket and versioning turned onTaraThe access key has permissions only on that bucket
Vault or OpenBao with Transit and an Ed25519 keyTaraHolds the package signing key, in place of a key file
ClickHouse 26.xRyomaNative port. Needs one write user for the Collector and two read-only users for Grafana
Your organization's private registryTara, RyomaHolds the tara-api, tara-portal, and ryoma-api images
Internal network or VPNGrafanaDon't expose Grafana to the Internet
ClamAVTaraOptional. 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.

bash
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 Ryoma

Common 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:

ValueMeaning
image.api.*, image.portal.*Images and tags
ingress.host, ingress.tls.secretNameTara's single host. TARA_PUBLIC_URL and TARA_PORTAL_URL are derived from it
s3.endpoint, s3.bucket, s3.region, s3.pathStyleThe package store. The access key lives in the Secret
signing.vault.addr, .mount, .keyThe signing key in Transit. The Vault token lives in the Secret as TARA_SIGNING_VAULT_TOKEN
worker.modeembedded 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.enabledTurns on malware scanning
config.*The rest of the non-secret TARA_* variables, such as ryomaUrl, grafanaUrl, apps
secrets.existingSecretName of the existing Secret that holds the secret keys
migration.seedConfigtrue (default): the migration Job also runs tara-admin seed-config, which creates the organizations and loads the model catalog. It is idempotent
migration.existingSecretA 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.envproduction (default): the API and the worker refuse to start when their database role is a superuser or has BYPASSRLS
config.singleOrg, config.githubOrgOnly 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:

ValueMeaning
api.ingress.hostThe address Phillip sends telemetry to, that is PHILLIP_RYOMA_URL
config.taraUrl, config.taraKeysTara issues identities to Ryoma, along with Tara's public key
collector.clickhouseEndpoint, collector.rawTTLClickHouse 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.enabledOff by default. Turn it on only with an internal or VPN IngressClass
api.replicasNumber of ryoma-api replicas, 2 by default in production
config.scmPluginThe GitHub scm kit for Ryoma (RYOMA_SCM_PLUGIN), as name@version:sha256. Get the sha256 on the resource page on Tara
config.scmGitlabPluginThe 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.scmServerTokenOrgsDeprecated. 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.

  1. Prepare the external infrastructure: two PostgreSQL databases, the S3 bucket, the Transit key, ClickHouse, DNS, certificates, and the Secrets for both charts.

  2. On ClickHouse, create the otel database, the write user for the Collector, and the two read-only users for Grafana with the sample files in Ryoma/deploy/clickhouse/, or the equivalent SQL commands.

  3. Install Tara:

    bash
    helm upgrade --install tara Tara/deploy/helm/tara -n tara -f values-production.yaml -f custom.yaml

    The migration job runs before the API changes version. If the migration fails, the old version keeps running.

  4. 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 from GET /v1/signing-keys and put it in the Ryoma and Phillip configuration.

  5. Release Phillip and the tools to Tara with tara-admin phillip-release and tara-admin tool-release. Then create a read-only Tara token for Ryoma with ph tara tokens create ryoma and put it in Ryoma's Secret.

  6. Install Ryoma with helm upgrade --install ryoma Ryoma/deploy/helm/ryoma -n ryoma -f .... ryoma-api migrates PostgreSQL and ClickHouse on its own. The Collector creates the otel_logs table, so the ryoma-api pod has a generous startupProbe to wait for the Collector to come up first.

  7. Create the read-only Grafana user on PostgreSQL with the file Ryoma/deploy/postgres/grafana-user.sql.

  8. Register the grafana client in Tara's TARA_OAUTH_CLIENTS, then upgrade Tara. The grafana-init job 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 target docs-web) with its own Ingress on docs.host (default phillipcli.cloud). Self-hosters build it with DOCS_TARA_URL (the Tara address shown in articles), DOCS_URL and DOCS_DEVELOP_URL (the developer site it links to), and point the Portal at it with the DOCS_URL build argument. The status page calls Tara from the browser, so Tara's /healthz and /phillip/latest.json must allow the docs origin through CORS.
  • The developer site is the one you are reading (develop.enabled, image target develop-web, host develop.host, default developers.phillipcli.cloud). Build it with DOCS_PUBLIC_URL (the documentation site it links back to). Its Internal section is for admin console staff only: set develop.internal.enabled=true (it needs admin.enabled=true: readers sign in at the admin console with a staff account) and put TARA_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.

DataHow to back up
Tara's PostgreSQLpg_dump or a snapshot with WAL. This is the source of truth for versions, roles, and audit
S3 bucketTurn on versioning, and object lock or replication if available. Packages are immutable, so the bucket is almost append-only
Signing keyLives 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 PostgreSQLBack up the same way as Tara's
ClickHouseclickhouse-backup or a volume snapshot. Raw data expires on its own according to collector.rawTTL
GrafanaSnapshot the PVC or use an external database. You can rebuild dashboards from the chart

Verify after installing ​

Verify in order from easiest to hardest.

  1. Run helm lint and helm template for both charts.
  2. Call https://tara.phillipcli.cloud/healthz, which also checks PostgreSQL. Also call /install.sh to make sure the install script comes out correctly.
  3. Release a sample resource, then check that the package is in the bucket and the sha256 matches.
  4. From a real user machine, run ph setup and then ph tara install <resource>. Claude Code must download the package over HTTPS on its own, with the authentication header, and verify the sha256.
  5. Point PHILLIP_RYOMA_URL at Ryoma and run ph forge doctor. The ryoma-api log must show the user and organization, and the Grafana dashboards must show data.
  6. 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.

Further reading ​