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 |
|
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.
# 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
- Back up the database, the object bucket and secrets, and try the migrations on a restored copy first.
- Build the new image and stop every process of the previous version.
- Run
migrate, then startwebandworkers.
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).