Flagship (Multi-Server Coordination)

When deploying multiple motherships across different servers, the flagship feature ensures exactly one instance runs prelaunch jobs (migrations, setup) while the others — the escorts — wait for its ready signal.

┌─────────────────────────────────────────────────────────────┐
│                         FLEET                               │
│  ┌───────────┐    ┌───────────┐    ┌───────────┐            │
│  │ Server A  │    │ Server B  │    │ Server C  │            │
│  │ Mothership│    │ Mothership│    │ Mothership│            │
│  │ ⭐FLAGSHIP │    │  (escort) │    │  (escort) │            │
│  │           │    │           │    │           │            │
│  │ 1. uplinks│    │ 1. uplinks│    │ 1. uplinks│            │
│  │ 2. migrate│    │ 2. wait...│    │ 2. wait...│            │
│  │ 3. signal │───►│ 3. ready! │    │ 3. ready! │            │
│  │ 4. launch │    │ 4. launch │    │ 4. launch │            │
│  └───────────┘    └───────────┘    └───────────┘            │
└─────────────────────────────────────────────────────────────┘

• Uplinks are verified on all instances — each checks its own connectivity.
• Prelaunch jobs run on only one instance: the flagship.
• If the flagship fails, the entire deployment aborts.

Static election

Explicitly designate the flagship via environment variable:

[mothership.flagship]
enabled = true
election = "static"
static_flagship = "$MS_FLAGSHIP"  # truthy: "true", "1", "yes"

Or via command output:

[mothership.flagship]
enabled = true
election = "static"
static_flagship = { command = "hostname", equals = "server-a" }

Examples:

• Kamal: run the first host with MS_FLAGSHIP=true
• Heroku: { command = "printenv DYNO", equals = "web.1" }

PostgreSQL election

Automatic leader election using advisory locks (requires the tokio-postgres Cargo feature):

[mothership.flagship]
enabled = true
election = "postgres"
app_name = "myapp-production"
election_url = "$DATABASE_URL?sslmode=require"

app_name is the explicit election namespace: instances sharing the same PostgreSQL database and the same app_name coordinate with each other; different app_name values don’t. It is required for PostgreSQL election — use a stable, deployment-specific value like myapp-production or $RENDER_SERVICE_NAME. Allowed characters: ASCII letters, numbers, -, _.

Escorts wait for the flagship’s ready signal via LISTEN/NOTIFY.

By default, insecure PostgreSQL SSL modes (disable, allow, prefer) are rejected for flagship election. To bypass this (not recommended), set MOTHERSHIP_ALLOW_INSECURE_POSTGRES_SSLMODE=true.

Configuration reference

Field	Type	Default	Description
enabled	bool	false	Enable flagship coordination
election	string	"static"	Election backend: "static" or "postgres"
app_name	string	–	PostgreSQL election namespace; required for election = "postgres", supports $ENV expansion
election_url	string	–	PostgreSQL URL (supports $ENV expansion)
static_flagship	string/table	–	Env var ("$VAR") or command ({ command, equals })
prelaunch_timeout	u64	300	Seconds escorts wait for the flagship
election_timeout	u64	30	Seconds to acquire the lock