Deployment

Mothership runs in the foreground and supervises its fleet directly: killing mothership drains and lands the fleet. It is a process supervisor, not a deployment tool — it doesn’t fetch, build, or pull anything.

Where it fits

• Development: run your full stack (web, workers, websockets) with one command and one manifest.
• Single-server production: VPS, dedicated server, on-prem — mothership is the init-adjacent layer between systemd/Docker and your app processes.
• Containers: one mothership per container, supervising the processes inside it.
• Multi-server: same manifest everywhere, with Flagship coordinating prelaunch.

It is not a container orchestrator, service mesh, or database manager. Keep PostgreSQL and Redis outside the fleet and declare them as uplinks.

Containers and PID 1

When mothership runs as PID 1 on Linux, it enables an internal init shim:

• PID 1 becomes a minimal reaper/forwarder
• the real mothership runtime runs as a child process (PID > 1)

This avoids Tokio child-process supervision races under PID 1. You should still prefer an external init:

docker run --init ...

docker-compose.yml

services:
  mothership:
    init: true

With another runtime, use an equivalent tini-style init wrapper.

Example Dockerfile

FROM rust:1.97-alpine AS builder
COPY . /build
WORKDIR /build
RUN cargo build --release

FROM alpine:latest
COPY --from=builder /build/target/release/mothership /usr/local/bin/
COPY ship-manifest.toml /etc/mothership/
ENTRYPOINT ["mothership", "-c", "/etc/mothership/ship-manifest.toml"]

Graceful shutdown

On SIGTERM/SIGINT mothership enters Draining: ships are terminated in reverse dependency order, process trees are cleaned up, and the run ends in Landed. See Lifecycle states.

Multi-server rollouts

Deploying the same manifest to several servers (Kamal, Heroku-style platforms, plain SSH):

1. Enable Flagship so migrations run on exactly one instance per deploy.
2. Every instance verifies its own uplinks.
3. Put your load balancer in front of the binds, with PROXY protocol enabled to preserve client IPs.

Versioning

Mothership follows a pragmatic pre-1.0 policy:

• Patch (0.0.x): bug fixes, no breaking changes
• Minor (0.x.0): new features, config may change
• Major (x.0.0): no backward compatibility guarantee

License: BSD-3-Clause.