Guides

Practical end-to-end tutorials: walk the whole path — from an empty cluster to a working service across souls — and see how Soul Stack’s key operations fit together along the way.

Where Quick Start is a single host and a minimal five-minute demo, and the DSL / Modules / Configuration sections are reference material, the guides show coherent end-to-end workflows: what to do step by step, in what order, and why.

Where to start

If you’ve just finished Quick Start, continue from here. If your cluster isn’t up yet, start with Installation and Quick Start.

Souls onboardingConnect several hosts at once: registration, bootstrap tokens, soul init, soul run, verifying connected. Covens for targeting later.

Your first souls serviceThe full path: register a service (git + ref), create an incarnation on a coven, see it applied across several hosts, and verify the result.

Scenario orchestrationControl rollout order: rolling (serial:), run_once:, targeting by stable facts (where:), probing the live role, and a rolling restart via onchanges:.

Monitoring out of the boxMetrics via Prometheus scrape (:9090, pull) and traces via OpenTelemetry push; what to look at; a sample Destiny that installs an exporter on hosts.

Suggested order

A recommended sequence:

1. Souls onboarding — with no connected hosts there’s nothing to apply to.
2. Your first souls service — roll state out to those hosts.
3. Scenario orchestration — control exactly how state rolls out across all souls.
4. Monitoring out of the box — observe the cluster and hosts in operation.

Each guide stands on its own and links to the reference sections it needs — you don’t have to read them strictly in order.

Next steps

• Concepts — the vocabulary and mental model: Keeper, Souls, Destiny, Soulprint, Essence, Coven.
• DSL — the normative grammar for Destiny / Scenario / Essence.
• Operations — scaling, upgrades, backup, troubleshooting.