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

  1. Create the installation directory. This writes deploy/instance/application.env and deploy/instance/secrets with database, Django and encryption secrets. Existing directories are never overwritten and secrets are not printed.

    bash
    python3 deploy/configure.py \
      --hostname apps.example.com \
      --s3-bucket company-ai-files \
      --s3-endpoint https://storage.example.com   # leave out for AWS S3
    
  2. Fill s3_access_key and s3_secret_key from your secret manager. The credential needs ListBucket, GetObject, PutObject and DeleteObject on the bucket/prefix; readiness also calls HeadBucket.

  3. Build, start the database, check, migrate, create the first company and operator, then start web and workers.

    bash
    docker 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
    
  4. Open the printed /login address and sign in as operator@example.com with an email code. Without SMTP_URL, the code is in the web server log.

  • New installs start on PostgreSQL 18 (postgres:18-trixie); configure.py pins those two lines in deploy/.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_password file 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.

bash
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-USER iptables rules on the host; the compute check warns about it.
  • With scheduled backups (deploy/operations.py), put the two values in deploy/.env instead of export, and add delivery to writer_services in operations.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, set Host to the public host name and X-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):

    bash
    docker compose -f deploy/compose.production.yaml exec web mothership-recover operator@example.com
    

Next

Esc