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*