Mothership
Production install
Install Mothership with the production Compose file (PostgreSQL, an S3-compatible bucket, separate web and workers) and sign in as the first operator.
Production means deploy/compose.production.yaml: PostgreSQL, an existing S3-compatible bucket, separate web and worker services, and an HTTPS reverse proxy in front. The root compose.yaml and fly.toml are for development and previews.
What you need
- Docker Engine with Compose v2 or newer
- An HTTPS host name and reverse proxy
- An S3-compatible bucket (AWS S3, MinIO, R2 …), ideally with a prefix of its own and versioning
- At least 4 GiB of memory for the app and workers (plus the database and OS)
- For source builds or app backends, also a container registry and room for the executor → Source builds and app backends
Install
-
Create the installation directory. This writes
deploy/instance/application.envanddeploy/instance/secretswith database, Django and encryption secrets. Existing directories are never overwritten and secrets are not printed.bashpython3 deploy/configure.py \ --hostname apps.example.com \ --s3-bucket company-ai-files \ --s3-endpoint https://storage.example.com # leave out for AWS S3 -
Fill
s3_access_keyands3_secret_keyfrom your secret manager. The credential needs ListBucket, GetObject, PutObject and DeleteObject on the bucket/prefix; readiness also calls HeadBucket. -
Build, start the database, check, migrate, create the first company and operator, then start web and workers.
bashdocker compose -f deploy/compose.production.yaml build docker compose -f deploy/compose.production.yaml up -d db docker compose -f deploy/compose.production.yaml run --rm tools manage check_deployment --production docker compose -f deploy/compose.production.yaml run --rm migrate docker compose -f deploy/compose.production.yaml run --rm tools manage bootstrap_installation \ --organization acme --name 'Acme Corporation' --email operator@example.com docker compose -f deploy/compose.production.yaml up -d web workers -
Open the printed
/loginaddress and sign in asoperator@example.comwith an email code. WithoutSMTP_URL, the code is in the web server log.
- New installs start on PostgreSQL 18 (
postgres:18-trixie);configure.pypins those two lines indeploy/.env. Without them Compose starts 17, as for older installs. - Initialization is idempotent. It never resets credentials or elevates another account. Password options and the
bootstrap_passwordfile are no longer used.
Source builds and app backends
If you only upload frontend ZIPs that are already built, web and workers above are enough. For either of the following, also run the source build executor (delivery, manage application_worker).
- Developing apps from a connected Galpi project. Galpi only sends a source ZIP; Mothership does the build. Without an executor, build requests are not processed and wait.
- Apps with a Python or Node backend. The executor builds and starts the backend containers.
| What | Notes |
|---|---|
| Toolchain image | Build deploy/application/toolchain.Dockerfile, push it to a registry and pin it by digest in MOTHERSHIP_BUILD_IMAGE (only name@sha256:… is accepted) |
| Compute | A Docker socket or Kubernetes. Add, check and set the default in Service admin → Compute |
| With Kubernetes | A remote BuildKit (MOTHERSHIP_BUILDX_BUILDER) and an app image repository (MOTHERSHIP_IMAGE_REPOSITORY). Only the cluster Mothership runs in is supported for now |
With a Docker socket: the socket is mounted into the executor only, and app containers run on a network of their own, mothership-apps.
export MOTHERSHIP_BUILD_IMAGE=registry.example/toolchain@sha256:…
export MOTHERSHIP_DOCKER_GID=$(stat -c %g /var/run/docker.sock)
docker compose -f deploy/compose.production.yaml -f deploy/application/compose.docker.yaml up -d --build
- The Docker API cannot block connections from the app network to private ranges and the host. Block them with
DOCKER-USERiptables rules on the host; the compute check warns about it. - With scheduled backups (
deploy/operations.py), put the two values indeploy/.envinstead ofexport, and adddeliverytowriter_servicesinoperations.json. - Full settings and a Kubernetes example are in the repository's
deploy/managed-compute.md.
Reverse proxy
- Web listens on
127.0.0.1:8080. Terminate TLS at a trusted proxy, setHostto the public host name andX-Forwarded-Proto: https. - Strip client-supplied forwarding headers before setting your own. Proxies trusted for sign-in limits go in
MOTHERSHIP_TRUSTED_PROXIES. - Turn off buffering for SSE, allow requests as long as the stream deadline, and set the upload limit above the platform file limit.
Operators
-
People in
ADMIN_EMAILS(comma-separated) become operators at every start (manage ensure_operators). Remove an address from the list before demoting that person, or the next start promotes them again. -
When mail or SSO is lost, print a recovery link (one hour, single use):
bashdocker compose -f deploy/compose.production.yaml exec web mothership-recover operator@example.com
Next
- Operations: variables, backup and recovery, upgrades, health
- Using Mothership: opening companies and company admin
how to install · installation · deploy