Self-hosted, single organization
The shared PhillipCLI service lets anyone sign up and create organizations. A self-hosted install usually serves one company. For that case Tara has a single-organization mode: one fixed organization, no Create organization screen, and sign-in sources that come from your own configuration. This page covers how to turn it on, the database role that keeps organizations isolated, and how to move an install that still uses centers. It applies to both the single-host (Docker Compose) install and the Helm chart.
Turn on single-organization mode
Set TARA_SINGLE_ORG to the slug of your organization, for example acme (lowercase letters, digits, and hyphens).
| Setting | Single-host (deploy.env) | Helm |
|---|---|---|
| Organization slug | TARA_SINGLE_ORG=acme | config.singleOrg: acme |
| GitHub organization whose members join on their own (optional) | TARA_GITHUB_ORG=<github-org> | config.githubOrg: <github-org> |
With TARA_SINGLE_ORG set:
POST /v1/orgsis switched off (the API answers 403org_creation_disabled), and the Portal hides Create organization.- People who sign in through GitLab or OIDC join this organization with the role their group maps to (
admin,member, orviewer). See SSO sign-in and Prepare GitHub and GitLab. - If you also set
TARA_GITHUB_ORG, members of that GitHub organization join asmemberwhen they sign in, and Tara removes the membership at the next sign-in after they leave the GitHub organization. A join is refused when the organization has no free seat. The person can still sign in, and an owner or admin can free a seat or invite them.
Without TARA_SINGLE_ORG (the shared-service mode), GitHub sign-in has no organization check, nobody joins an organization just by signing in, and TARA_GITHUB_ORG is ignored with a warning in the log. In that mode GitLab and OIDC group mappings still go into the organization default, so installs that used them before keep working.
The organization must exist
Tara refuses to start if sign-in auto-join needs an organization that isn't in the database. The organization is created by tara-admin seed-config, which reads the orgs list in the seed configuration and runs in make migrate, in the single-host tara-migrate step, and in the Helm migration Job. The seed ships with the organizations aiforge (the official catalog) and default. So you have two choices: use TARA_SINGLE_ORG=default, or add your own organization to the orgs list and run the migration again. The command is safe to run many times.
What the environment variables only seed
TARA_GITHUB_ORG, TARA_GITLAB_PROVIDERS, and TARA_OIDC_PROVIDERS no longer decide who may sign in to the whole service. They only set up the sign-in sources of this one organization. On the shared service, per-organization sign-in setup moves into the Portal, which is coming soon.
First owner
Nobody joins just by signing in, so make the first person an owner after they sign in once:
tara-admin grant <login> acme owner
tara-admin staff create <login> --role moderator --email <email> # optional: staff account of the admin console that reviews the official catalogEveryone else joins through a group mapping, TARA_GITHUB_ORG, or an invitation (ph org invite <email> --role member, or Members in the Portal). The free plan allows 7 seats for owners, admins, and members. Viewers (BA, PO, PM, browser only) don't count.
The tara_app database role
Tara isolates organizations with PostgreSQL Row-Level Security (RLS), and RLS does nothing for a superuser or for a role with BYPASSRLS. So Tara uses two database roles:
| Role | Used by | Rights |
|---|---|---|
Database owner (for example tara) | tara-admin migrate, creating the app role, enabling pgvector | Owns the tables and runs migrations |
tara_app | tara-api, tara-worker, and every other tara-admin command | No superuser, no BYPASSRLS. Reads and writes data only, with no DDL. Default privileges cover tables that later migrations create |
The variables:
| Variable | Used by | Meaning |
|---|---|---|
TARA_DATABASE_URL | API, worker | Connection as tara_app, for example postgres://tara_app:<password>@db.example.com:5432/tara |
TARA_APP_DB_PASSWORD | Migration | Password of tara_app. When it is set, tara-admin migrate up creates or updates the role on every run and grants it on all tables |
TARA_MIGRATE_DATABASE_URL | Migration | Connection as the database owner. Defaults to TARA_DATABASE_URL |
TARA_ENV | API, worker | production makes both refuse to start when their database role is a superuser or has BYPASSRLS. Any other value only logs a warning |
Only the migration step should see the owner credentials. The API and the worker never need them.
Single-host (Docker Compose)
./init-env.sh generates TARA_APP_DB_PASSWORD in deploy.env. docker-compose.yml sets TARA_ENV: production, connects the API and the worker as tara_app, and gives the owner connection only to the one-time tara-migrate service and to tara-admin. Run admin commands with the same wrapper as before, for example dc run --rm --no-deps tara-admin grant <login> acme owner.
Helm
Put TARA_DATABASE_URL (as tara_app) in the main Secret (secrets.existingSecret). Put TARA_MIGRATE_DATABASE_URL and TARA_APP_DB_PASSWORD in a second Secret that only the migration Job reads (migration.existingSecret). The password in TARA_APP_DB_PASSWORD must be the one inside TARA_DATABASE_URL. config.env is production by default.
If the API doesn't start
An error that names tara_app means the API or the worker connected as a superuser or a BYPASSRLS role while TARA_ENV=production. Set TARA_APP_DB_PASSWORD, run the migration so the role exists, and point TARA_DATABASE_URL at tara_app. To check by hand, run this as the owner and expect f:
select rolsuper or rolbypassrls from pg_roles where rolname = 'tara_app';Move from the old center model
Centers were replaced by organizations. The migration moves your data in one step when you upgrade, and it needs no dump:
| Before | After |
|---|---|
Resources of the rnd center (the official catalog) | Resources of the platform organization aiforge, official tier |
| All other centers and their resources | The organization default, private tier |
rnd admin and reviewer | Staff account of the admin console (moderator), and Owner of default |
| Admin and reviewer of another center | Admin |
| Publisher and member | Member |
| PM | Viewer |
| Ryoma projects of a center | Projects of default |
| API tokens and telemetry tokens | Attached to default |
The old centers and memberships tables are dropped after the data moves. Take a backup before you upgrade.
- Back up the Tara PostgreSQL database.
- Add
TARA_APP_DB_PASSWORDto your configuration (single-host: run./init-env.sh, which only adds the missing value; Helm: add it to the migration Secret together withTARA_MIGRATE_DATABASE_URL). - Set
TARA_SINGLE_ORG=defaultif you want to keep your current organization, or add a new organization to the seed configuration and use its slug. - Upgrade. The migration runs first, creates
tara_app, moves the data, andseed-configmakes sure the organizations exist. The API then reconnects astara_app. - Check with
tara-admin members, then sign in to the Portal and confirm that people have the roles in the table above.
Manifests with metadata.forge.center are still read and show a deprecation warning. Change them to metadata.forge.org. See Roles and permissions for the role model.