Goal
Show the end-to-end flow from dashboard action to runtime state.Prerequisites
- Understand the core concepts
Workflow
The pieces
- Control plane: the API and the source of truth for your resources and their state.
- Workers: background processors that run builds, provision databases, meter billing, and run backups.
- Agent: runs on each node, executes runtime instructions, runs your containers, and serves ingress through Caddy.
- Nodes: the runtime hosts where workloads actually run.
A deploy, end to end
- A dashboard action creates a control-plane request.
- For source deploys, a build runs (BuildKit) and the resulting image is pushed to the registry.
- The control plane places the workload on a healthy node and instructs that node’s agent.
- The agent pulls and runs the workload and Caddy routes the domain to it.
- Operations and resource detail views surface the resulting health, logs, and recovery state.
Where a failure lives
Because each stage is distinct, a failure has an address. A build error is a worker/build problem; a workload that builds but will not place is a control-plane/placement problem; a placed workload that never reports healthy is usually an agent or runtime problem on the node. Knowing which stage failed tells you which page to open.Expected result
You can reason about where a failure occurred: control plane, worker, node agent, or workload runtime.
Common failures
Related guides
Connect your first node
Bootstrap a Linux host into StackShift and verify it is healthy enough to host workloads.
Operations overview
The operations area is the cross-resource health and runtime visibility surface for StackShift.
Recovery states, logs, and troubleshooting
Read the operation state on a resource — its status, current step, attempt count, retryable flag, and last error — together with logs, instead of treating a single “error” badge as the whole story.