Self-Hosted Kubernetes Platform

Your own Vercel/Heroku alternative - push code, get running apps with SSL for €6.50/month.

✨ What You Get

• 🚀 Auto-deployment - Push to git, app automatically builds and deploys
• 🔒 Automatic HTTPS - Let's Encrypt SSL certificates
• 📦 No Dockerfile needed - kpack auto-detects your framework (Next.js, Angular, Python, Go, etc.)
• 📊 Web Dashboard - Deploy and monitor apps from your browser
• 💰 Dirt cheap - Single Hetzner server for €6.50/month

🎯 Stack

• Talos Linux - Immutable, secure OS
• Flux - GitOps deployment
• kpack - Cloud-native builds (no Docker needed)
• Traefik - Automatic routing + SSL
• Headlamp - Web UI with deployment dashboard

🚀 Quick Start (Local)

# Install Bun (if not already installed)
curl -fsSL https://bun.sh/install | bash

# Install minikube (if not already installed)
# macOS: brew install minikube
# Linux: curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
# Windows: choco install minikube

# Install dependencies
cd .dev && bun install && cd ..

# Start local cluster
./dev up

# Access dashboard (token will be displayed automatically)
./dev dashboard
# Open: http://localhost:8080

# Deploy apps from the web UI or CLI
./dev apps

📦 Deploy Your App

From the Web UI (Recommended)

1. Run ./dev dashboard to open Headlamp
2. Open http://localhost:8080
3. Copy and paste the login token displayed in the terminal
4. Click "Deploy Center" in sidebar
5. Click "+ Deploy New App"
6. Enter your git URL
7. Select framework (Next.js, Angular, etc.)
8. Click "Deploy"

From CLI

./dev apps              # Interactive selection
./dev logs my-app       # View logs
./dev builds            # Monitor builds
./dev dashboard         # Open Headlamp

🌍 Production Deployment

Prerequisites:

• Terraform installed
• kubectl installed
• Hetzner Cloud account with API token
• Domain name (for SSL certificates)

1. Configure Infrastructure

cd terraform
cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars - add your Hetzner API token

2. Deploy Cluster

terraform init
terraform apply

# Get kubeconfig
terraform output -raw germany_kubeconfig > kubeconfig
export KUBECONFIG=$(pwd)/kubeconfig

3. Configure DNS

Point wildcard DNS to your server:

*.yourdomain.com  →  A  →  YOUR_SERVER_IP

Get your server IP: terraform output germany_ips

4. Setup GitOps with Flux

Flux automatically syncs your infrastructure from git:

# Install flux CLI
curl -s https://fluxcd.io/install.sh | bash

# Bootstrap Flux (installs Flux + auto-deploys everything in ./infra)
flux bootstrap github \
  --owner=YOUR_GITHUB_USERNAME \
  --repository=self-hosted-gitops-cluster-starter \
  --branch=main \
  --path=./infra \
  --personal

That's it! Flux will automatically:

• Install all infrastructure components (kpack, Traefik, Headlamp, etc.)
• Watch your git repo for changes
• Auto-deploy updates when you push to git

Wait 2-3 minutes, then access Headlamp at https://headlamp.yourdomain.com

📁 Project Structure

.
├── dev                # 🎯 CLI tool (./dev up to start)
├── terraform/         # Hetzner Cloud infrastructure
├── infra/            # Core components (Flux, kpack, Traefik, etc.)
└── apps/             # Your applications (templates included)

🎨 Included Apps (Examples)

• bunjs-example - Bun.js web app
• immich - Photo management (self-hosted Google Photos)
• supabase - Firebase alternative (PostgreSQL + Auth + Storage)

💰 Cost Breakdown

Single Server (Germany):

• Hetzner CX22: €6.50/month (2 vCPU, 4GB RAM, 40GB SSD)
• Domain: ~€10/year

Total: ~€6.50/month (excluding domain)

Dual Region (optional):

• 2x CX22: €13/month
• High availability across Finland + Germany

🔧 Commands Reference

./dev up              # Start local cluster
./dev down            # Stop cluster
./dev apps            # Select apps to run
./dev logs <app>      # View app logs
./dev builds          # Monitor kpack builds
./dev dashboard       # Open Headlamp UI

🤔 How It Works

1. Push code to GitHub
   ↓
2. kpack detects changes
   ↓
3. Builds container image (no Dockerfile needed)
   ↓
4. Pushes to registry
   ↓
5. Flux deploys to cluster
   ↓
6. Traefik routes traffic + provisions SSL
   ↓
7. Your app is live! 🎉

📚 Documentation

• Local Development: Run ./dev up and deploy apps from Headlamp UI
• Production Setup: Follow the 5-step guide above
• Add Custom App: See apps/bunjs-example/ for template
• Troubleshooting: Check build logs in Headlamp "Deploy Center"

🛠️ Tech Stack Details

Component	Purpose	Why?
Talos	OS	Immutable, secure, no SSH needed
Flux	GitOps	Auto-syncs from git
kpack	Builds	Cloud-native, no Docker daemon
Traefik	Ingress	Auto SSL, easy config
Headlamp	UI	Deploy from browser
Cilium	Networking	eBPF-based, fast

🎯 Use Cases

• Personal projects
• Side projects
• Small team apps
• Learning Kubernetes
• Portfolio hosting
• Replace Vercel/Heroku for hobby projects

📖 Learn More

• Talos Linux
• Flux
• kpack
• Headlamp
• Hetzner Cloud

⚠️ Not Recommended For

• Mission-critical production apps (single node = no HA)
• High traffic apps (1 server has limits)
• Enterprise compliance requirements

For those cases, consider managed Kubernetes (GKE, EKS, AKS) or multi-node setup.

🤝 Contributing

PRs welcome! This is a learning-friendly project.

📄 License

MIT - Use freely!

---

Built with ❤️ for developers who want simple, cheap, self-hosted deployments.