Quickstart

1. Install

   cargo install mothership

   Or build from source:

   git clone https://github.com/seuros/mothership.git
   cd mothership
   cargo build --release

   Optional Cargo features keep the binary small (~10.4 MB default):

   Feature	Size impact	Adds
   tui	+0.3 MB	TUI dashboard (--tui flag)
   wasm	+8.4 MB	WASM payload processing
   tokio-postgres	+0.5 MB	PostgreSQL flagship election

   cargo build --release --features "tui,wasm,tokio-postgres"

2. Initialize a manifest

   mothership init

   This creates ship-manifest.toml in the current directory. A minimal Rails-style fleet looks like:

   [mothership]
   metrics_port = 9090
   compression = true
   
   [mothership.bind]
   http = "0.0.0.0:80"
   
   [[mothership.prelaunch]]
   name = "migrate"
   command = "rails"
   args = ["db:migrate"]
   
   [[fleet.web]]
   name = "app"
   command = "bundle"
   args = ["exec", "rails", "server"]
   bind = "tcp://127.0.0.1:3000"
   healthcheck = "/up"
   routes = [{ bind = "http", pattern = "/.*" }]
   
   [[fleet.workers]]
   name = "sidekiq"
   command = "bundle"
   args = ["exec", "sidekiq"]
   critical = false

3. Validate

   # Offline manifest validation
   mothership clearance
   
   # Validation + uplink connectivity checks (needs network access)
   mothership preflight
   
   # Inspect the routing table
   mothership chart

4. Launch

   mothership            # run the fleet
   mothership --tui      # with the TUI dashboard (requires the tui feature)
   mothership --only web # only ships tagged "web"

What happens on launch

1. Uplinks are verified — if a configured database or cache is unreachable, mothership aborts.
2. Prelaunch jobs run in dependency order — a failing job aborts the launch.
3. Bays dock and ships launch, respecting depends_on ordering.
4. Traffic flows: binds accept connections, routes match, requests proxy to ships and bays.

See Lifecycle states for the full state machine.

Running in containers

When mothership runs as PID 1 on Linux it enables an internal init shim (PID 1 becomes a minimal reaper; the real runtime runs as a child). Prefer an external init anyway:

docker-compose.yml

services:
  mothership:
    init: true

More in Deployment.