docker cluster bootstrap contract

[MdSadiqMd]

Summary

Implements the Docker cluster bootstrap contract for generic deployments. Operators can now deploy clustered Mesh apps to Docker without manual identity construction or repo-local hacks.

What changed:

• Runtime auto-derives node identity from hostname when MESH_NODE_NAME is not set
• New MESH_NODE_HOST env var lets operators specify advertised addresses
• meshc init --template todo-api --db postgres generates a production-ready docker-compose.yml
• All 8 bootstrap environment variables are explicitly documented

Why:

• Existing Docker deployments required manual MESH_NODE_NAME construction (e.g., todo-postgres@10.0.0.5:4370)
• No ready-to-use Docker Compose template existed
• Bootstrap contract was implicit and undocumented

Result:
Operators only need MESH_CLUSTER_COOKIE + MESH_DISCOVERY_SEED + MESH_NODE_HOST to cluster. The runtime handles identity resolution automatically.

Related issues

Verification

# Unit tests
cd compiler/mesh-rt
cargo test bootstrap::tests --lib
# Result: 12/12 passed (new tests for hostname identity, fallback order, IPv6)

cd ../mesh-pkg
cargo test scaffold --lib
# Result: 10/10 passed (includes docker-compose.yml generation)

# Integration test
cd ../../examples/todo-postgres
meshc build --target x86_64-unknown-linux-gnu .
docker compose config
# Result: Valid configuration

docker compose up -d
docker compose ps
# Result: postgres (healthy), node1 (up), node2 (up)

docker compose exec node1 env | grep MESH_
# Result: All 6 MESH_* variables set correctly

docker compose exec node1 getent hosts mesh-cluster
# Result: Resolves to both node1 and node2 IPs

meshc cluster status node1@node1:4370 --cookie change-me-in-production --json
# Result: Cluster status returned successfully

docker compose down -v

Bootstrap environment contract:

Variable	Required	Default	Purpose
MESH_CLUSTER_COOKIE	Yes (cluster)	—	Shared HMAC-SHA256 secret for node authentication
MESH_DISCOVERY_SEED	Yes (cluster)	—	DNS name that resolves to all node IPs
MESH_CLUSTER_PORT	No	4370	TCP port for inter-node communication
MESH_NODE_NAME	No	auto	Explicit name@host:port identity (overrides auto)
MESH_NODE_HOST	No	hostname	Advertised address peers use to reach this node
MESH_CONTINUITY_ROLE	No	primary	primary or standby continuity role
MESH_CONTINUITY_PROMOTION_EPOCH	No	0	Monotonic counter for split-brain prevention
MESH_DISCOVERY_INTERVAL_MS	No	5000	DNS re-resolution interval in milliseconds

Identity resolution order: MESH_NODE_NAME > FLY_* env > hostname + MESH_NODE_HOST

Checklist

• I linked the relevant issue, or explained why there is not one.
• I ran the smallest relevant verification and listed it above.
• I updated docs, examples, or templates if public behavior changed.
• I did not commit secrets, local env files, generated binaries, or temp artifacts.
• I called out breaking changes, migration notes, or follow-up work if needed.

Notes for reviewers

Key design decisions:

1. Hostname-based identity is the third fallback (after explicit MESH_NODE_NAME and Fly env). This preserves backward compatibility while enabling Docker/K8s deployments.

2. MESH_NODE_HOST is optional with a sensible default (system hostname). Operators only set it when the container hostname isn't routable (e.g., overlay networks).

3. Docker Compose uses network aliases (mesh-cluster) so MESH_DISCOVERY_SEED=mesh-cluster resolves to all node IPs. This is simpler than hardcoding IPs.

4. Cross-compilation documented because macOS/Windows users will hit "exec format error" without --target x86_64-unknown-linux-gnu. The README now includes this upfront.

Areas to focus on:

• compiler/mesh-rt/src/dist/bootstrap.rs lines 350-390: hostname identity resolution logic
• examples/todo-postgres/docker-compose.yml: network alias pattern for discovery
• examples/todo-postgres/README.md: bootstrap contract table completeness

Not breaking:

• Existing MESH_NODE_NAME and Fly deployments work unchanged
• New hostname path only activates when neither explicit name nor Fly env is set

[Copilot]

Pull request overview

Implements a Docker-friendly cluster bootstrap contract so operators can run clustered Mesh apps in generic container environments without manually constructing MESH_NODE_NAME.

Changes:

• Runtime: adds MESH_NODE_HOST and hostname-based node identity fallback when neither MESH_NODE_NAME nor Fly identity env is set.
• Tooling/examples: adds a two-node docker-compose.yml for todo-postgres and updates scaffolding to generate it.
• Docs: documents the full bootstrap environment contract and identity resolution order for Docker Compose usage.

Reviewed changes

Copilot reviewed 5 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
examples/todo-postgres/README.md	Adds Docker Compose clustered run instructions and documents the bootstrap env contract.
examples/todo-postgres/docker-compose.yml	Introduces a 2-node cluster + Postgres compose setup using mesh-cluster DNS aliasing.
examples/todo-postgres/.env.example	Adds guidance for using MESH_NODE_HOST in container environments.
compiler/mesh-rt/src/dist/bootstrap.rs	Adds MESH_NODE_HOST, hostname identity fallback, and unit tests for resolution order/IPv6.
compiler/mesh-rt/Cargo.toml	Adds the hostname dependency for runtime hostname resolution.
compiler/mesh-pkg/src/scaffold.rs	Updates scaffolding docs and generates docker-compose.yml for the postgres todo template.
Cargo.lock	Locks the new hostname dependency.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[snowdamiz]

lgtm!