Hybrid Cloud Infrastructure - Connecting a public VPS gateway with a private homelab through secure tunnels.
KyleHub Infrastructure is a monorepo containing all the Infrastructure-as-Code (IaC) for the KyleHub platform. It implements a hybrid cloud architecture that combines the global reach of a cloud VPS with the compute power and storage capacity of a private homelab.
| Zone | Purpose | Components |
|---|---|---|
| Gateway (VPS) | Public ingress, authentication, routing | Pangolin, Zitadel, Traefik |
| Homelab (Private) | Compute, storage, AI workloads | Proxmox, NEWT Agent, Services |
| Network | Secure tunneling | NEWT/WireGuard tunnels, DreamMachine Pro |
Key Principle: The homelab has zero open ports. All public traffic flows through the VPS via encrypted WireGuard tunnels managed by Pangolin.
infrastructure/
├── Makefile # Deployment commands
├── ARCHITECTURE.md # Detailed architecture docs
├── documentation/ # Docusaurus documentation site
│
├── gateway-vps/ # VPS Stack (Public Gateway)
│ ├── compose.yaml # Pangolin, Zitadel, Traefik
│ ├── .env.example # Environment template
│ ├── init_config.sh # Config generator
│ └── config/ # Traefik, Pangolin configs
│
└── homelab-core/ # Homelab Stack (Private Services)
├── compose.yaml # NEWT Agent, Langfuse, etc.
└── services/ # Service-specific configs
- Docker & Docker Compose installed
- Domain with DNS management (Cloudflare recommended)
- VPS with public IP (Hetzner, DigitalOcean, etc.)
- (Optional) Proxmox homelab with DreamMachine Pro / AdGuard
git clone https://github.com/KyleHub-Dev/infrastructure.git
cd infrastructurecd gateway-vps
# Copy and configure environment
cp .env.example .env
nano .env # Fill in your values# Generate Pangolin config
./init_config.sh
# Deploy the stack
docker compose up -dcd homelab-core
# Copy and configure environment
cp .env.example .env
nano .env # Fill in your values# Deploy the stack
docker compose up -dAfter both stacks are running, configure services in the Pangolin Dashboard:
- Access
https://pangolin.yourdomain.com - Complete initial setup (admin account, organization)
- Configure Zitadel as the Identity Provider
- Add NEWT tunnels for homelab services
- Create resources for each service you want to expose
📖 Full documentation: See the Docusaurus docs or visit docs.kylehub.dev
| Command | Description |
|---|---|
make deploy-vps | Pull images and start the VPS stack |
make deploy-home | Pull images and start the homelab stack |
make logs-vps | Follow VPS container logs |
make logs-home | Follow homelab container logs |
make sync-docs | Build the documentation site |
| Service | Description |
|---|---|
| Pangolin | Zero Trust gateway, reverse proxy, tunnel management |
| Zitadel | Identity provider (OIDC/OAuth2), SSO for all services |
| Traefik | Edge router with automatic SSL via Let's Encrypt |
| Gerbil | WireGuard tunnel endpoint for NEWT connections |
| Service | Description |
|---|---|
| NEWT Agent | Connects homelab to VPS via WireGuard tunnel |
| Langfuse | LLM observability and prompt management |
| Proxmox | Hypervisor for VMs and containers |
| (Future) AdGuard Home | Network-wide DNS and ad blocking |
1. Deploy VPS Stack → Pangolin, Zitadel, Traefik running
2. Complete Pangolin Setup → Admin account, organization created
3. Configure Zitadel → OIDC provider ready
4. Deploy Homelab Stack → NEWT agent connects to VPS
5. Add Resources in Pangolin → Services accessible via subdomains
6. Configure SSO → Zitadel protects all services
Full documentation is available in the documentation/ folder (Docusaurus) and covers:
- Getting Started - Prerequisites, initial setup
- Gateway VPS Setup - Complete VPS deployment guide
- Homelab Setup - Proxmox, networking, NEWT configuration
- Post-Deployment - Pangolin dashboard, Zitadel SSO, service exposure
- Services - Individual service setup guides
- Troubleshooting - Common issues and solutions
cd documentation
npm install
npm run start # Development server
npm run build # Production buildThis project is licensed under the MIT License. See LICENSE for details.
Maintained by the KyleHub Organization