Skip to content

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).

SettingSingle-host (deploy.env)Helm
Organization slugTARA_SINGLE_ORG=acmeconfig.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/orgs is switched off (the API answers 403 org_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, or viewer). See SSO sign-in and Prepare GitHub and GitLab.
  • If you also set TARA_GITHUB_ORG, members of that GitHub organization join as member when 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:

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

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

RoleUsed byRights
Database owner (for example tara)tara-admin migrate, creating the app role, enabling pgvectorOwns the tables and runs migrations
tara_apptara-api, tara-worker, and every other tara-admin commandNo superuser, no BYPASSRLS. Reads and writes data only, with no DDL. Default privileges cover tables that later migrations create

The variables:

VariableUsed byMeaning
TARA_DATABASE_URLAPI, workerConnection as tara_app, for example postgres://tara_app:<password>@db.example.com:5432/tara
TARA_APP_DB_PASSWORDMigrationPassword 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_URLMigrationConnection as the database owner. Defaults to TARA_DATABASE_URL
TARA_ENVAPI, workerproduction 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:

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

BeforeAfter
Resources of the rnd center (the official catalog)Resources of the platform organization aiforge, official tier
All other centers and their resourcesThe organization default, private tier
rnd admin and reviewerStaff account of the admin console (moderator), and Owner of default
Admin and reviewer of another centerAdmin
Publisher and memberMember
PMViewer
Ryoma projects of a centerProjects of default
API tokens and telemetry tokensAttached to default

The old centers and memberships tables are dropped after the data moves. Take a backup before you upgrade.

  1. Back up the Tara PostgreSQL database.
  2. Add TARA_APP_DB_PASSWORD to your configuration (single-host: run ./init-env.sh, which only adds the missing value; Helm: add it to the migration Secret together with TARA_MIGRATE_DATABASE_URL).
  3. Set TARA_SINGLE_ORG=default if you want to keep your current organization, or add a new organization to the seed configuration and use its slug.
  4. Upgrade. The migration runs first, creates tara_app, moves the data, and seed-config makes sure the organizations exist. The API then reconnects as tara_app.
  5. 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.

Further reading ​