Server configuration variables
This page is for the people who run the services. It names the groups, and lists the variables that changed with organizations. The other values are secrets or depend on the environment. The variables for email, Google, the GitHub App, SSO secrets, and service tokens are in the Self-hosting reference.
Tara (TARA_*)
Organizations and database roles. These variables are new or changed with the Organization model. The values are placeholders.
| Variable | Default | Meaning |
|---|---|---|
TARA_SINGLE_ORG | empty | Slug of the only organization of a self-hosted install, for example acme. When set, creating organizations is switched off, and GitLab and OIDC group mappings (and TARA_GITHUB_ORG members) join this organization. Empty is the shared multi-organization mode. See Self-hosted, single organization |
TARA_ENV | development | production makes the API and the worker refuse to start when their database role is a superuser or has BYPASSRLS. Any other value only logs a warning |
TARA_DATABASE_URL | local PostgreSQL | What the API and the worker connect as. In production use the role tara_app, for example postgres://tara_app:<password>@db.example.com:5432/tara |
TARA_MIGRATE_DATABASE_URL | TARA_DATABASE_URL | Connection as the database owner, used only by tara-admin migrate. Keep it out of the API and worker environment |
TARA_APP_DB_PASSWORD | empty | Password of the role tara_app. When set, tara-admin migrate up creates or updates the role on every run and grants it on all tables |
TARA_GITHUB_ORG | empty | Changed. It no longer gates sign-in. GitHub sign-in is open to anyone. With TARA_SINGLE_ORG set, members of this GitHub organization join the organization as member. Without TARA_SINGLE_ORG it is ignored and Tara logs a warning |
TARA_GITLAB_PROVIDERS, TARA_OIDC_PROVIDERS | empty | Changed. They only seed the sign-in sources of the initial organization. In groups, the value is now an organization role (admin, member, or viewer). Old center codes are still read and count as member, with a warning. An element with "connectOnly": true is used only to connect an organization's GitLab group (it isn't a sign-in source and may have empty groups); its OAuth redirect URI is <TARA_PUBLIC_URL>/auth/gitlab-connect/callback. See Prepare GitHub and GitLab |
TARA_GRAFANA_VIEWER_ROLES | owner,admin | Organization roles, besides viewer, that Tara lists for Grafana's per-organization orgs. For operators only. See Grafana for operators |
Centers were replaced by organizations. What no longer applies: a center code in a groups mapping, and setting TARA_GITHUB_ORG to let people sign in with GitHub.
Variable groups.
| Group | Used for |
|---|---|
TARA_DATABASE_*, TARA_S3_*, TARA_ARTIFACT_* | PostgreSQL, S3 or equivalent package storage |
TARA_PUBLIC_*, TARA_PORTAL_*, TARA_MARKETPLACE_* | Public address, Portal, marketplace name |
TARA_OAUTH_*, TARA_OIDC_*, TARA_GITHUB_*, TARA_GITLAB_*, TARA_SCM_* | Sign-in and GitHub and GitLab connections |
TARA_SIGNING_* | Signing keys, from files or KMS |
TARA_NOTIFY_* | Notification plugins, pinned as name@version:sha256, with secrets per kit |
TARA_RYOMA_PUBLIC_URL | The address clients (Phillip) send telemetry to, published at GET /v1/client-config and written into Phillip's config by /install.sh, ph tara login and ph setup. Defaults to TARA_RYOMA_URL; set it when Tara reaches Ryoma on an internal address (for example http://ryoma-api:8090) but clients use a public one |
TARA_RYOMA_URL, TARA_DELEGATION_KEY | Where Tara reads Ryoma metrics, and the key (at least 32 random characters, held only by tara-api) that signs the short-lived read-only token Tara sends on behalf of each user |
TARA_GRAFANA_*, TARA_BANDUM_* | Links to Grafana and Bandum for display |
TARA_EMBEDDING_* | Embeddings for the Knowledge base (optional) |
TARA_REVIEW_*, TARA_YARA_*, TARA_MALWARE_*, TARA_CLAUDE_BIN | Submission checks: malware scanning and running claude plugin validate |
TARA_KEYS, TARA_PLUGIN_*, TARA_NODE_* | Trusted keys and the plugin sandbox |
Ryoma (RYOMA_*)
| Group | Used for |
|---|---|
RYOMA_DATABASE_*, RYOMA_CLICKHOUSE_*, RYOMA_RAW_TTL | PostgreSQL, the ClickHouse analytics store, raw data retention |
RYOMA_OTLP_*, RYOMA_COLLECTOR_* | The telemetry receiver and the Collector |
RYOMA_TARA_*, RYOMA_AUTH_* | Tara token authentication |
RYOMA_SCM_*, RYOMA_WEBHOOK_*, RYOMA_PLUGIN_* | Task sync through SCM kits, webhooks |
RYOMA_NOTIFY_*, RYOMA_DIGEST_*, RYOMA_GUARDRAILS_*, RYOMA_HEALTH_*, RYOMA_RISK_* | Notifications, the weekly digest, Guardrails alerts, project health thresholds |
RYOMA_LEADER_*, RYOMA_BACKGROUND | Running multiple ryoma-api replicas |
New in Ryoma.
| Variable | Default | Meaning |
|---|---|---|
RYOMA_TARA_SCM_TOKEN | RYOMA_TARA_TOKEN | The Tara token Ryoma uses to get short-lived read-only GitHub tokens for an organization's GitHub App installation. It needs the scm scope |
RYOMA_SCM_GITLAB_PLUGIN | empty | name@version:sha256 of kit-scm-gitlab, or a local directory. Lets Ryoma read GitLab repositories (given as URLs) of organizations that have a GitLab connection, with the token Tara issues. Needs RYOMA_SCM_PLUGIN and RYOMA_TARA_SCM_TOKEN |
RYOMA_SCM_SERVER_TOKEN_ORGS | empty | Deprecated. Comma-separated slugs of organizations that may use the server's own read-only SCM token (RYOMA_SCM_TOKEN). It is only a fallback for single-organization or GitLab installs and is never used for an organization with a GitHub App. Helm: config.scmServerTokenOrgs |
Bandum (BANDUM_*)
Phillip configures local Bandum itself, so you rarely set these by hand. The main variables are BANDUM_DATABASE_URL, BANDUM_SCM_PLUGIN, BANDUM_SCM_TOKEN, BANDUM_TARA_URL, BANDUM_TARA_KEYS, BANDUM_ORG, and BANDUM_TIMEZONE. For GitHub App installs, BANDUM_TARA_SCM_TOKEN (default BANDUM_TARA_TOKEN) is the Tara token with the scm scope, and BANDUM_SCM_SERVER_TOKEN_ORGS is deprecated, as for Ryoma. To read GitLab repositories of organizations with a GitLab connection, also set BANDUM_SCM_GITLAB_PLUGIN (name@version) with BANDUM_SCM_GITLAB_PLUGIN_SHA256, or BANDUM_SCM_GITLAB_PLUGIN_DIR for a local copy. The host comes from the connection.
BANDUM_ORG is new. It is the slug of the organization that an online Bandum serves, [a-z0-9-] only, for example acme. Besides official packages (aiforge), Bandum loads only packages of that organization's private store, and a plugin name may carry the organization, as in acme/kit-x@1.0.0:<sha256>. Empty means official packages only. Community packages are always refused. A local Bandum reads the current organization from Phillip's configuration and doesn't need it.
Removed: BANDUM_GITHUB_CLIENT_ID, BANDUM_GITHUB_CLIENT_SECRET, and BANDUM_GITHUB_ORG are no longer used. The Bandum web signs in through Tara, and Bandum logs a warning if you still set them.
Don't put secrets in the repo
Variables that hold tokens, passwords, or keys must live in the environment, the secret store, or your organization's secret-management system. Don't put them in files you commit.
For the PHILLIP_* variables on a user's machine, see Configuration variables.