homelab/.planning/codebase/STACK.md

Technology Stack

Analysis Date: 2026-02-04

Languages

Primary:

• Bash - Infrastructure automation, API wrappers, system integration

  • Helper scripts at ~/bin/ for service APIs
  • Installation and setup in pve-homelab-kit/install.sh

• Python 3.12.3 - Management tools, monitoring, bot automation

  • Virtual environment: ~/venv/ (activated with source ~/venv/bin/activate)
  • Primary usage: API clients, Telegram bot, helper scripts

Runtime

Environment:

• Python 3.12.3 (system)
• Bash 5+ (system shell)

Package Manager:

• pip v24.0 (Python package manager)
• Lockfile: Virtual environment at ~/venv/ (not traditional pip.lock)

Frameworks

Core Infrastructure:

• Proxmox VE (v8.x) - Hypervisor/container platform on core.georgsen.dk
• Proxmox Backup Server (PBS) v2.x - Backup infrastructure (10.5.0.6:8007)
• LXC Containers - Primary virtualization method
• KVM VMs - Full VMs when needed (mail server VM 200)
• Docker/Docker Compose - Application deployment via Dockge (10.5.0.10)

Application Frameworks:

• Nginx Proxy Manager (NPM) v2.x - Reverse proxy, SSL (10.5.0.1:80/443/81)
• Dockge - Docker Compose stack management UI (10.5.0.10:5001)
• Forgejo v10.0.1 - Self-hosted Git server (10.5.0.14:3000)
• Technitium DNS - DNS server with API (10.5.0.2:5380)

Monitoring & Observability:

• Uptime Kuma - Service/endpoint monitoring (10.5.0.10:3001)
• Beszel - Server metrics dashboard (10.5.0.10:8090)

Messaging:

• Stalwart Mail Server - Mail server (VM 200, IP 65.108.14.164)
• Snappymail - Webmail UI (djmaze/snappymail:latest, 10.5.0.10:8888)

Data Storage:

• DragonflyDB - Redis-compatible in-memory datastore (10.5.0.10:6379)
  • Password protected, used for session/cache storage
• PostgreSQL 13+ (VMID 103, 10.5.0.109) - Community managed database
• Redis/DragonflyDB (VMID 104, 10.5.0.111) - Session/cache store

Key Dependencies

Python Packages (in ~/venv/):

Proxmox API:

• proxmoxer v2.2.0 - Python API client for Proxmox VE
  • File: ~/bin/pve (list, status, start, stop, create-ct operations)

Monitoring APIs:

• uptime-kuma-api v1.2.1 - Uptime Kuma monitoring client
  • File: ~/bin/kuma (monitor management)
• pocketbase v0.15.0 - Beszel dashboard backend client
  • File: ~/bin/beszel (system monitoring)

Communications:

• python-telegram-bot v22.5 - Telegram Bot API
  • File: ~/telegram/bot.py (homelab management bot)

HTTP Clients:

• requests v2.32.5 - HTTP library for API calls
• httpx v0.28.1 - Async HTTP client
• urllib3 v2.6.3 - Low-level HTTP client

Networking & WebSockets:

• websocket-client v1.9.0 - WebSocket client library
• python-socketio v5.16.0 - Socket.IO client
• simple-websocket v1.1.0 - WebSocket utilities

Utilities:

• certifi v2026.1.4 - SSL certificate verification
• charset-normalizer v3.4.4 - Character encoding detection
• packaging v25.0 - Version/requirement parsing

Configuration

Environment:

• Bash scripts: Load credentials from ~/.config/{service}/credentials files
  • ~/.config/pve/credentials - Proxmox API token
  • ~/.config/dns/credentials - Technitium DNS API
  • ~/.config/beszel/credentials - Beszel dashboard API
  • ~/.config/uptime-kuma/credentials - Uptime Kuma API
  • ~/.config/forgejo/credentials - Forgejo Git API
• Python scripts: Similar credential loading pattern
• Telegram bot: ~/telegram/credentials file with TELEGRAM_BOT_TOKEN

Build & Runtime Configuration:

• Python venv activation: source ~/venv/bin/activate
• Helper scripts use shebang: #!/home/mikkel/venv/bin/python3 or #!/bin/bash
• All scripts in ~/bin/ are executable and PATH-accessible

Documentation:

• CLAUDE.md - Development environment guidance
• homelab-documentation.md - Infrastructure reference (22KB, comprehensive)
• README.md - Quick container/service overview
• TODO.md - Pending maintenance tasks

Platform Requirements

Development/Management:

• Container: LXC on Proxmox VE (VMID 102, "mgmt")
• OS: Debian-based Linux (venv requires Linux filesystem)
• User: mikkel (UID 1000, group georgsen GID 1000)
• SSH: Pre-installed keys for accessing other containers/VMs
• Network: Tailscale VPN for external access, internal vmbr1 (10.5.0.0/24)

Production (Core Server):

• Provider: Hetzner AX52 (Helsinki)
• CPU: AMD Ryzen 7 3700X
• RAM: 64GB ECC
• Storage: 2x 1TB NVMe (RAID0 via ZFS)
• Public IP: 65.108.14.165/26 (BGP routed)
• Network bridges: vmbr0 (public), vmbr1 (internal), vmbr2 (vSwitch)

Backup Target:

• Synology NAS (home network via Tailscale)
• Protocol: CIFS/SMB 3.0 over Tailscale
• Mount point on PBS: /mnt/synology (bind-mounted as datastore)

Deployment & Access

Service URLs:

• Proxmox Web UI: https://65.108.14.165:8006 (public, home IP whitelisted)
• NPM Admin: http://10.5.0.1:81 (internal only)
• DNS Admin: https://dns.georgsen.dk (home IP whitelisted via access list)
• PBS Web UI: https://pbs.georgsen.dk:8007 (home IP whitelisted)
• Dockge Admin: https://dockge.georgsen.dk:5001 (home IP whitelisted)
• Forgejo: https://git.georgsen.dk (public)
• Status Page: https://status.georgsen.dk (Uptime Kuma)
• Dashboard: https://dashboard.georgsen.dk (Beszel metrics)

SSL Certificates:

• Provider: Let's Encrypt via NPM
• Challenge method: HTTP-01
• Auto-renewal: Handled by NPM

---

Stack analysis: 2026-02-04