Mothership

Operations

Environment variable names, company SSO, health checks, backup and recovery, upgrades and company data export.

Environment variable names

Settings the family shares use Galpi's names. The older MOTHERSHIP_… names keep working and win when both are set. The full list is in .env.example and the repository's docs/operations.md.

Family name Mothership's older name Meaning
PUBLIC_URL MOTHERSHIP_PUBLIC_URL The address people open; sign-in links use it
SECRETS_KEY MOTHERSHIP_SECRET_ENCRYPTION_KEYS Seals company credentials and OIDC secrets. Galpi's form (openssl rand -base64 32) or a Fernet key, comma-separated for rotation (the first encrypts, the rest decrypt)
ADMIN_EMAILS (new) Made operators at every start
SMTP_URL, MAIL_FROM MOTHERSHIP_EMAIL_*, MOTHERSHIP_DEFAULT_FROM_EMAIL Mail
APP_LANG (new) Default language ko (default) or en
S3_* MOTHERSHIP_S3_* File storage
LLM_*, MODE_*_MODEL MOTHERSHIP_AI_* Models (read only with LLM_API_FORMAT=openai)
GALPI_URL added to MOTHERSHIP_GALPI_ALLOWED_ORIGINS This Galpi may request development connections
NARU_URL added to MOTHERSHIP_TENANT_ALLOWED_INTEGRATION_ORIGINS Company admins may connect this Naru as an external tool

Also common: DATABASE_URL (PostgreSQL in production), DATABASE_POOL_MAX (pool per process, default 10), MOTHERSHIP_PROCESS_ROLE (all, web, workers), MOTHERSHIP_TRUSTED_PROXIES, MOTHERSHIP_TENANT_AI_ALLOWED_ORIGINS.

Company SSO

OIDC is registered per company. In Service admin → Companies, an operator picks the company, enters the Issuer URL, Client ID and Client secret, and gets the Callback URL to register with the provider (…/api/auth/v1/sso/<company>/callback). Register members automatically from verified emails makes people the IdP verified members of that company. A company SSO session is limited to that company and never grants another company's access or operator rights. With one SSO company the sign-in card shows its button on top; with more, it asks for the company's address.

Health

Address Checks
GET /healthz/live Only that the process is alive
GET /healthz/ready Database, object storage and every worker kind. 503 with reasons (database_pool_exhausted, workers_unavailable …) when not
GET /api/admin/v1/health Worker freshness and last progress, for operators

Workers heartbeat every ten seconds. Readiness needs at least one live runtime, documents, automation and Knowledge worker (MOTHERSHIP_HEALTH_WORKER_MAX_AGE, default 90 seconds).

Backup and recovery

Keep encryption keys apart from backups. Restoring the database without the original keys can't decrypt company credentials.

bash
# A consistent backup: stop every writer first
docker compose -f deploy/compose.production.yaml stop web workers
docker compose -f deploy/compose.production.yaml run --rm tools manage backup_installation \
  --output /backups/before-upgrade --writers-stopped
docker compose -f deploy/compose.production.yaml up -d web workers
docker compose -f deploy/compose.production.yaml run --rm tools manage restore_installation \
  --input /backups/before-upgrade --verify-only

It writes a PostgreSQL dump, the S3 objects and SHA-256 checksums of everything, never passwords or keys. To restore, use an empty database and an empty bucket/prefix, the same keys, writers stopped, and restore_installation. Don't migrate before restoring.

Scheduled encrypted backups, retention and signed alerts are in docs/operations-automation.md; acceptance checks against a customer's integrations in docs/deployment-acceptance.md.

Upgrades

  1. Back up the database, the object bucket and secrets, and try the migrations on a restored copy first.
  2. Build the new image and stop every process of the previous version.
  3. Run migrate, then start web and workers.

Before going back to a previous release, check for migrations it doesn't know. App releases are pinned per company and environment, so upgrading the platform doesn't change any company's app versions.

Company data

Company owners see the company's data inventory and get a signed export in Company admin → Company data, including employees' company-private records in both environments. Large exports, permanent erasure and selective recovery are operator commands: export_company, erase_company, restore_company (docs/company-data.md).

Esc