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

OTLP collector baseline with optional central gateway, retention, and dashboards

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 requires both cloud and local infrastructure. If you only need a single environment (local or cloud), 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
OTel Collector	Metrics baseline	Per-node collector, OTLP export
monitoring-core gateway	Fan-in	Optional central OTLP gateway
VictoriaMetrics	Metrics retention	Optional backend for multi-node or longer retention
Grafana	Visualization	Optional dashboard surface when backend tier is enabled
Logs lane	Log forwarding	Opt-in; only enable when the deployment needs it

Quick start

Define your hybrid setup

stack-spec.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

addons:
  - monitoring-core

observability:
  monitoring:
    signals:
      metrics: true
      logs: true
    gateway:
      enabled: true
    backend:
      enabled: true
      grafana:
        enabled: true

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:
  monitoring:
    signals:
      metrics: true
      logs: true
    collector:
      profile: full
    gateway:
      enabled: true
    backend:
      enabled: true
      retentionPeriod: 30d
      grafana:
        enabled: true

Platform components

Coolify — Multi-node PaaS

Coolify manages deployments across your nodes. While the Base Kit defaults to Coolify for single-environment setups, the Modern Homelab Kit leverages its multi-node capabilities for hybrid topologies:

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 stack-spec.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 + Coolify	Docker Swarm	Docker + Coolify
Network	Local only	Local LAN	VPN overlay (Headscale)
Public Access	Optional (Cloudflare Tunnel)	Optional	Default
Monitoring	OTLP collector baseline	OTLP collector + gateway planning	Collector baseline + monitoring-core
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 ports 80 and 443 are open on the cloud node
Verify DNS provider API credentials in Traefik config

Monitoring gaps

Verify OTel Collector is running on all nodes
Check the OTLP receiver or gateway endpoint is reachable over the VPN path
Inspect TechStack /api/v1/monitor/health for ingest-lane and backend diagnostics
If enabled, verify VictoriaMetrics and Grafana separately from the collector baseline

Migration from the Base Kit

Backup all data

stackkit backup --all --output ./backup

Provision cloud node

Add a cloud node to your stack-spec.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

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

​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