Configure a StackSpec

stack-spec.yaml is the desired-intent document for one StackKits workspace. Let the released CLI create the complete document, then change only the intent you understand.

stackkit init basement-kit --owner-source=local
stackkit validate

The released CLI writes a complete native StackSpec and establishes local owner custody outside it. Keep the generated apiVersion: the installed release’s CUE contracts supply its fields, defaults and constraints.

Common fields to review

Intent	Current field	Guidance
Workspace identity	`metadata.name`	Keep it DNS-compatible and stable after the first apply.
Kit	`kit.slug`	Use `basement-kit` for a home site or `cloud-kit` for an existing cloud host.
Generated output	`generation.outputRoot`	Keep generated artifacts separate from the StackSpec.
Persistent data	`storage.dataRoot`	Use an absolute path on storage you operate and back up.
Backups	`storage.backupRoot`	Keep it separate from the primary data root.
Stack data	`storage.stacksRoot`	Use an absolute path owned by the local operator.
Local domain	`network.domain.base`	The Basement Kit release default is `home.test`; use a domain whose resolution you control.

This is an excerpt, not a replacement for the complete generated document:

{
  "metadata": { "name": "family-home" },
  "kit": { "slug": "basement-kit" },
  "generation": {
    "outputRoot": "deploy",
    "strategy": "kit-template",
    "target": "compose"
  },
  "storage": {
    "dataRoot": "/opt/stackkit/data",
    "backupRoot": "/opt/stackkit/backups",
    "stacksRoot": "/opt/stackkit/stacks",
    "volumeDriver": "local"
  },
  "network": {
    "mode": "private",
    "domain": { "base": "home.test" }
  }
}

Select the released Files workload

The Basement and Cloud Kit contracts expose files as an optional workload for the Documents & Files use case; the use-case catalog lists the components declared by the published release. This selection was validated and generated with the released CLI:

{
  "workloads": {
    "files": {
      "alternative": "cloudreve",
      "runtimeAdapterRef": "standalone-compose",
      "placement": {
        "siteRefs": ["home"],
        "nodeRefs": ["main"]
      }
    }
  }
}

Merge the workloads object into the complete StackSpec produced by init. The home site and main node are the released Basement defaults; use identifiers already present in your generated document. Since v0.21.11, the placement block is optional. A workload selected without one receives the governed empty-placement defaults from the embedded CUE contracts, so programmatic StackSpec authors no longer need CLI-specific boilerplate.

Do not copy this selection for Photos or Vault and invent secret values. Those workloads require owner-bound secret custody. Since v0.21.11, run stackkit secrets materialize after selecting such a workload and before generate to establish that custody explicitly.

Validate every change

stackkit validate
stackkit generate
stackkit plan --json

validate checks the current StackSpec, generate creates governed output, and plan inspects the exact resolved plan without invoking an executor. If any command fails, fix the StackSpec; do not patch files below deploy/. Continue with Review, apply, and verify.

Get started

Guides

Reference

Configure a StackSpec

Common fields to review

Select the released Files workload

Validate every change

​Common fields to review

​Select the released Files workload

​Validate every change

Common fields to review

Select the released Files workload

Validate every change