Skip to main content
StackKits are architecture-pattern-based infrastructure blueprints built on three concepts: StackKit (pattern), Node-Context (environment), and Add-Ons (composable extensions).

What's a StackKit?

A StackKit defines an architecture pattern — how services relate to each other. Combined with auto-detected Node-Context and composable Add-Ons, it produces a fully validated, context-aware infrastructure configuration.

​
The problem StackKits solve

You want to set up a homelab. You’ve heard of:
Reverse Proxy
  • Traefik?
  • Caddy?
  • nginx?
Authentication
  • Authelia?
  • Authentik?
  • Keycloak?
Management
  • Portainer?
  • Dockge?
  • Coolify?
Photos
  • Immich?
  • Photoprism?
  • Nextcloud?
Questions:
  • Which tools work well together?
  • How do I configure them correctly?
  • What are the best practices?
  • How do I avoid security mistakes?
StackKits answer all of these.

​
The three concepts

​
1. StackKit = Architecture pattern

A StackKit defines how infrastructure is organized, not how many servers you need.
StackKitPatternWhat it means
baseSingle-environmentAll services in one deployment target
modernHybrid infrastructureLocal + cloud connected via VPN overlay
haHigh-availability clusterRedundancy, failover, quorum consensus
A base StackKit can run on 3 Raspberry Pis. An ha StackKit can run on 1 powerful server. The StackKit defines the pattern, not the scale.

​
2. Node-Context = auto-detected environment

ContextHow it’s detectedWhat it affects
localPhysical hardware, no cloud metadataSelf-signed TLS, Dokploy, local DNS
cloudCloud provider metadata detectedLet’s Encrypt, Coolify, public DNS
piARM + low memory or RPi detectionARM images, reduced services, tmpfs

​
3. Add-Ons = composable extensions

Add-Ons replace the old monolithic variant system. They stack and compose:
kombination.yaml
stackkit: base
addons:
  - monitoring    # Prometheus + Grafana
  - backup        # Restic + S3
  - media         # Jellyfin + *arr

​
Available StackKits

Base Kit

Single-environment
  • Docker Compose
  • Any node count
  • Context-aware defaults
  • Perfect first homelab

High Availability Kit

High-availability
  • Docker Swarm cluster
  • Keepalived VIP
  • 3+ nodes recommended
  • Automatic failover

Modern Homelab Kit

Hybrid infrastructure
  • Local + cloud nodes
  • VPN overlay built-in
  • Coolify PAAS
  • Public endpoints

​
How StackKits work

​
Context-driven defaults

The combination of StackKit × Context produces curated default configurations:
localcloudpi
baseDokploy, self-signed TLSCoolify, Let’s EncryptLean Docker, reduced services
modernTailscale exit node, hybrid DNSMulti-cloud meshEdge relay role
haSwarm + KeepalivedCloud HA + managed LBNot recommended

​
3-Layer architecture

StackKits use a strict 3-layer architecture for maximum reusability:
LayerPurposeManaged by
L1: FoundationSystem, security, packages, core identity (LLDAP, Step-CA)OpenTofu
L2: PlatformContainer runtime, PAAS, ingress, platform identityOpenTofu
L3: ApplicationsUser services deployed by PAASPAAS (Dokploy/Coolify)

​
CUE schema definition

Each StackKit is defined in CUE, a powerful configuration language:
base-kit/stackfile.cue
package base_homelab

import "github.com/kombihq/stackkits/base"

#BaseHomelabKit: base.#BaseStackKit & {
    metadata: {
        name: "base-kit"
        version: "4.0.0"
    }
    
    // Services with dependency constraints
    services: {
        traefik: #TraefikService
        dokploy: #DokployService
        // ...
    }
    
    // Context-aware PAAS selection
    if _context == "cloud" {
        paas: type: "coolify"
    }
}
CUE provides type checking, validation, and default values — catching errors before deployment, not after.

​
Validation flow

​
Progressive capability model

StackKits operates at different levels depending on how you use it:

​
Example: base StackKit

​
Minimal configuration

kombination.yaml
version: "2.0"
stackkit: base
domain: home.example.com

nodes:
  - name: server-01
    host: 192.168.1.100

# That's it! Traefik, Dokploy, TinyAuth are auto-configured
# Context is auto-detected (local in this case)

​
With Add-Ons

kombination.yaml
version: "2.0"
stackkit: base
domain: home.example.com

nodes:
  - name: server-01
    host: 192.168.1.100

addons:
  - monitoring       # Prometheus + Grafana
  - backup           # Restic backups
  - media            # Jellyfin + *arr stack

​
StackKit comparison

Featurebasemodernha
PatternSingle-environmentHybrid infrastructureHA cluster
Container runtimeDocker ComposeDocker + CoolifyDocker Swarm
Typical nodes1 (supports N)2+ (multi-environment)3+ (quorum)
ComplexityLowMediumHigh
FailoverNoNoYes
Best forFirst homelabHybrid setupsProduction workloads

​
Customization

​
Override defaults

kombination.yaml
stackkit: base

services:
  traefik:
    dashboard: true
  monitoring:
    retention: 30d

​
Add-On ecosystem

Add-OnCategoryCompatible with
monitoringObservabilitybase, modern, ha
backupDatabase, modern, ha
vpn-overlayNetworkingmodern, ha
gpu-workloadsComputebase, modern
mediaApplicationsbase, modern
smart-homeIoTbase
ci-cdDevelopmentbase, modern, ha

​
Next steps

Base Kit details

Explore services and configuration options

CUE basics

Learn the configuration language

Quick start

Deploy your first StackKit