The stack-spec.yaml file (also accepted as kombination.yaml) is your deployment contract. This reference documents all available fields and their valid values.
Top-level fields
| Field | Type | Required | Description |
|---|
version | string | Yes | Spec version (currently "1.0") |
stackkit | string | Yes | StackKit to use (base-kit, ha-kit, modern-homelab) |
meta | object | Yes | Metadata about your homelab |
nodes | array | Yes | Server definitions |
services | array/object | Yes | Services to deploy |
meta:
name: my-homelab # Required: unique name
domain: home.example.com # Required: base domain
email: you@example.com # Optional: for Let's Encrypt
| Field | Type | Required | Description |
|---|
name | string | Yes | Unique homelab identifier (alphanumeric, hyphens) |
domain | string | Yes | Base domain for services |
email | string | No | Email for TLS certificate generation |
Nodes section
nodes:
- name: server-1
type: hypervisor
connection:
host: 192.168.1.100
user: root
ssh_key: ~/.ssh/id_ed25519
resources:
cpu: 4
memory: 16384
Node fields
| Field | Type | Required | Description |
|---|
name | string | Yes | Unique node identifier |
type | string | Yes | Node type: hypervisor, docker, bare-metal |
connection | object | Yes | How to reach this node |
resources | object | No | Resource constraints |
Connection fields
| Field | Type | Required | Description |
|---|
host | string | Yes | IP address or hostname |
port | int | No | SSH port (default: 22) |
user | string | No | SSH user (default: root) |
ssh_key | string | No | Path to SSH private key |
Services section
Services can be specified as a simple list or as detailed objects:
# Simple: enable with defaults
services:
- traefik
- immich
- vaultwarden
# Detailed: customize per service
services:
traefik:
enabled: true
config:
dashboard: true
log_level: INFO
immich:
enabled: true
config:
upload_limit: 10GB
Environment variables
Services support environment variable overrides:
services:
immich:
enabled: true
env:
UPLOAD_LOCATION: /data/photos
DB_PASSWORD: "${IMMICH_DB_PASSWORD}"
Never hardcode secrets in your stack-spec.yaml. Use environment variable references with ${VAR_NAME} syntax.
Validation
Validate your spec before deployment:
The validator checks:
- Required fields are present
- Types match the CUE schema
- Node connections are reachable
- Service dependencies are satisfied
- No port conflicts exist
Example: Complete spec
version: "1.0"
stackkit: base-kit
meta:
name: family-cloud
domain: home.example.com
email: admin@example.com
nodes:
- name: main-server
type: docker
connection:
host: 192.168.1.100
user: deploy
ssh_key: ~/.ssh/id_ed25519
services:
traefik:
enabled: true
config:
dashboard: true
vaultwarden:
enabled: true
immich:
enabled: true
config:
upload_limit: 50GB
homepage:
enabled: true
