Modern Homelab Kit

The Modern Homelab Kit brings multi-node hybrid infrastructure to your homelab. Designed for advanced users who need public-facing services, cloud+local server setups, and full observability across nodes.

Schema-only — This StackKit has a CUE schema defined but is not yet functional. Use the Base Kit for production deployments.

Overview

Key features

Multi-Node Docker

Deploy across cloud VPS and local servers

Coolify PaaS

Professional deployment platform for multi-node setups

VPN Overlay

Headscale/Tailscale for secure inter-node communication

Full Observability

Prometheus, Grafana, Loki (PLG) monitoring stack

Automatic TLS

Let’s Encrypt certificates via Traefik

Public Access

Services accessible from the internet by default

Requirements

Resource	Cloud Node (VPS)	Local Node	Total Minimum
Nodes	1 VPS	1+ local	2+
CPU	2 cores	4 cores	6 cores
RAM	4 GB	8 GB	12 GB
Storage	50 GB SSD	100 GB	150 GB
Network	Public IPv4, 1 Gbps	LAN access	—

Additional prerequisites:

Own domain with DNS control (e.g., Cloudflare, Hetzner DNS)
DNS provider API access for automated TLS provisioning
SSH access to all nodes

The Modern Homelab Kit has higher complexity and resource requirements than the Base Kit. If you only need a single local server, use the Base Kit instead.

Architecture deep dive

Hybrid topology

The Modern Homelab Kit connects cloud and local infrastructure using a VPN overlay: Traffic flow:

Public requests hit Traefik on the cloud VPS
Traefik routes to Coolify-managed applications
Applications on local nodes are reached via the Headscale VPN tunnel
Local nodes never expose ports to the public internet

Observability stack

Component	Purpose	Default Config
Prometheus	Metrics collection	15d retention, 15s scrape interval
Grafana	Visualization	Pre-built dashboards
Loki	Log aggregation	7d retention
Promtail	Log shipping	Per-node agent
Node Exporter	Hardware metrics	Per-node agent
cAdvisor	Container metrics	Per-node agent
Alertmanager	Alert routing	Discord/Email

Quick start

Define your hybrid setup

kombination.yaml

stackkit: modern-homelab

domain: homelab.example.com
email: you@example.com

nodes:
  - name: cloud-entry
    type: cloud
    provider:
      type: hetzner
      region: fsn1
      size: cx21
      image: debian-12

  - name: local-server
    type: local
    network:
      localIp: 192.168.1.100
      subnet: 192.168.1.0/24

Configure VPN overlay

vpn:
  enabled: true
  provider: headscale
  magicDns: true

Enable services

services:
  # Reverse proxy (cloud node)
  traefik:
    enabled: true
    acme: true
    acmeEmail: you@example.com

  # PaaS platform (cloud node)
  coolify:
    enabled: true

  # VPN control server (cloud node)
  headscale:
    enabled: true

  # Monitoring
  prometheus:
    enabled: true
    retention: 15d

  grafana:
    enabled: true

  loki:
    enabled: true
    retention: 7d

Deploy infrastructure

stackkit validate
stackkit generate
stackkit deploy

Configuration reference

Node configuration

Cloud Node
Local Node

nodes:
  - name: cloud-entry
    type: cloud
    hostname: cloud-entry

    provider:
      type: hetzner        # hetzner, digitalocean, vultr, linode
      region: fsn1
      size: cx21           # 2 vCPU, 4 GB RAM
      image: debian-12

    docker:
      version: "24.0"
      dataRoot: /var/lib/docker

    ssh:
      user: root
      port: 22

nodes:
  - name: local-server
    type: local
    hostname: local-server

    provider:
      type: bare-metal

    network:
      localIp: 192.168.1.100
      subnet: 192.168.1.0/24

    docker:
      version: "24.0"
      dataRoot: /var/lib/docker

    labels:
      storage: "true"
      role: application

VPN configuration

vpn:
  enabled: true
  provider: headscale
  derpEnabled: true
  derpRegions:
    - default
  magicDns: true

The VPN overlay creates an encrypted mesh between all nodes. Headscale is the self-hosted Tailscale control server — no third-party dependency required.

Monitoring configuration

observability:
  prometheus:
    retention: 15d
    storage: 50Gi
    scrapeInterval: 15s

  grafana:
    dashboards:
      - node-health
      - docker-containers
      - traefik-traffic
      - coolify-deployments

  loki:
    retention: 7d

  alertmanager:
    receivers:
      - name: discord
        webhook: https://discord.com/api/webhooks/xxx
      - name: email
        to: alerts@example.com

Platform components

Coolify — Multi-node PaaS

Coolify manages deployments across your nodes. Unlike Dokploy (used in the Base Kit for single nodes), Coolify provides:

Multi-node deployment via SSH
Git-based deployments (push to deploy)
Built-in database management
Application monitoring and logs
Resource limits per container

coolify:
  autoUpdate: false
  pushEnabled: true
  instanceSettings:
    isRegistrationEnabled: false
    isAutoUpdateEnabled: false
  resources:
    cpuLimit: "2.0"
    memoryLimit: "2048m"

Service placement

Services are placed on specific nodes based on their role:

Service	Placement	Reason
Traefik	Cloud node	Public entry point, TLS termination
Coolify	Cloud node	Needs SSH access to all nodes
Headscale	Cloud node	VPN coordination server
Prometheus + Grafana	Cloud node	Accessible remotely
Applications	Local node(s)	Data stays on-premises
Storage/NAS	Local node(s)	Physical disk access
Promtail + Node Exporter	All nodes	Per-node monitoring agents

Adding more nodes

# Add to kombination.yaml
nodes:
  # ... existing nodes

  - name: local-media
    type: local
    network:
      localIp: 192.168.1.101
      subnet: 192.168.1.0/24
    labels:
      role: media-server

stackkit deploy --node local-media

The new node is automatically joined to the Headscale VPN mesh and registered in Coolify.

Security

Network isolation

Local nodes are never directly exposed to the internet
All inter-node traffic is encrypted via Headscale VPN
Traefik handles TLS termination for public services
Coolify enforces resource limits per container

Authentication

auth:
  provider: pocketid      # PocketID for SSO
  twoFactor: true
  allowedDomains:
    - example.com

Firewall rules

The StackKit configures firewall rules automatically:

Port	Cloud Node	Local Node	Purpose
22	Open	LAN only	SSH access
80	Open	Closed	HTTP redirect
443	Open	Closed	HTTPS traffic
41641	Open	Open	Headscale/WireGuard
All others	Closed	Closed	—

Comparison with other StackKits

Feature	Base Kit	High Availability Kit	Modern Homelab Kit
Nodes	1	2+ (local)	2+ (cloud + local)
Platform	Docker + Dokploy	Docker Swarm	Docker + Coolify
Network	Local only	Local LAN	VPN overlay (Headscale)
Public Access	Optional (Cloudflare Tunnel)	Optional	Default
Monitoring	Basic (Uptime Kuma)	Prometheus + Grafana	Full PLG stack
Domain Required	No	No	Yes
Complexity	Low	Medium	High
Status	v1.0 (production)	vision-only	schema-only

Troubleshooting

VPN connection issues

Check Headscale status: headscale nodes list
Verify Tailscale agent on local node: tailscale status
Test connectivity: tailscale ping <cloud-node>
Check firewall: ensure UDP port 41641 is open on both sides

Coolify cannot reach local node

Verify VPN tunnel is established
Check SSH access via VPN IP: ssh root@<tailscale-ip>
Ensure Docker is running on the target node
Check Coolify server settings for the correct VPN IP

TLS certificate errors

Verify DNS records point to cloud node public IP
Check Traefik ACME logs: docker logs traefik
Ensure port 80 and 443 are open on the cloud node
Verify DNS provider API credentials in Traefik config

Monitoring gaps

Verify Promtail and Node Exporter are running on all nodes
Check Prometheus targets: navigate to prometheus.yourdomain.com/targets
Ensure VPN tunnel is stable (metrics travel over VPN)
Check Grafana data source configuration

Migration from the Base Kit

Backup all data

stackkit backup --all --output ./backup

Provision cloud node

Add a cloud node to your kombination.yaml and provision it:

stackkit: modern-homelab  # Changed from base-kit

nodes:
  - name: cloud-entry
    type: cloud
    provider:
      type: hetzner
      region: fsn1
      size: cx21
      image: debian-12

  - name: local-server   # Your existing server
    type: local
    network:
      localIp: 192.168.1.100

Deploy hybrid infrastructure

stackkit generate
stackkit deploy

Restore data on local node

stackkit restore --from ./backup --node local-server

Overview

Available Kits

How-To

Explanations

Reference

Modern Homelab Kit

Overview

Key features

Multi-Node Docker

Coolify PaaS

VPN Overlay

Full Observability

Automatic TLS

Public Access

Requirements

Architecture deep dive

Hybrid topology

Observability stack

Quick start

Configuration reference

Node configuration

VPN configuration

Monitoring configuration

Platform components

Coolify — Multi-node PaaS

Service placement

Adding more nodes

Security

Network isolation

Authentication

Firewall rules

Comparison with other StackKits

Troubleshooting

Migration from the Base Kit

Next steps

Monitoring Setup

Coolify Guide

Overview

Available Kits

How-To

Explanations

Reference

​Overview

​Key features

Multi-Node Docker

Coolify PaaS

VPN Overlay

Full Observability

Automatic TLS

Public Access

​Requirements

​Architecture deep dive

​Hybrid topology

​Observability stack

​Quick start

​Configuration reference

​Node configuration

​VPN configuration

​Monitoring configuration

​Platform components

​Coolify — Multi-node PaaS

​Service placement

​Adding more nodes

​Security

​Network isolation

​Authentication

​Firewall rules

​Comparison with other StackKits

​Troubleshooting

​Migration from the Base Kit

​Next steps

Monitoring Setup

Coolify Guide

Overview

Key features

Requirements

Architecture deep dive

Hybrid topology

Observability stack

Quick start

Configuration reference

Node configuration

VPN configuration

Monitoring configuration

Platform components

Coolify — Multi-node PaaS

Service placement

Adding more nodes

Security

Network isolation

Authentication

Firewall rules

Comparison with other StackKits

Troubleshooting

Migration from the Base Kit

Next steps