viktor/infra
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
infra/.planning/codebase/STACK.md
Viktor Barzin c8e9c41afc docs: map existing codebase
2026-02-23 20:54:27 +00:00

5 KiB
Raw Blame History

Technology Stack

Analysis Date: 2026-02-23

Languages

Primary:

  • HCL (HashiCorp Configuration Language) - Terraform/Terragrunt infrastructure definitions
  • Bash - Scripting and cluster management (scripts/ directory)
  • YAML - Kubernetes resource definitions and configuration
  • Python - Monitoring and utility scripts in stacks/platform/modules/
  • TypeScript/JavaScript - k8s-portal frontend and webhook-handler (stacks/platform/modules/k8s-portal/, stacks/webhook_handler/)

Secondary:

  • Go - Various utilities
  • Dockerfile - Container image definitions across stacks

Runtime

Environment:

  • Kubernetes v1.34.2 (5 nodes: k8s-master + k8s-node1-4)
  • Linux (Ubuntu cloud images on Proxmox VMs)
  • Bash shell for automation

Package Manager:

  • npm (Node.js) - for k8s-portal web UI development
    • Lockfile: package-lock.json present
  • pip (Python) - for utility scripts
  • Terraform/Terragrunt - manages all infrastructure dependencies

Frameworks

Core:

  • Terraform 1.x - Infrastructure-as-Code orchestration
  • Terragrunt - State isolation wrapper around Terraform (terragrunt.hcl in each stack)
  • Kubernetes - Container orchestration (kubectl, Helm, kustomize patterns)

Testing:

  • Playwright ^1.58.2 - E2E testing framework (root package.json)

Build/Dev:

  • Helm 3.1.1 - Kubernetes package manager (provider version via Terraform)
  • Svelte - Frontend framework for k8s-portal (stacks/platform/modules/k8s-portal/files/ Node.js project)

Key Dependencies

Critical:

  • hashicorp/terraform (Kubernetes 3.0.1) - Kubernetes API provider
  • hashicorp/helm (3.1.1) - Helm release management
  • telmate/proxmox (3.0.2-rc07) - Proxmox VM management (stacks/infra/)
  • cloudflare/cloudflare (4.52.5) - DNS and tunnel management (stacks/platform/modules/cloudflared/)
  • hashicorp/null (3.2.4) - Utility provider for local operations
  • hashicorp/random (3.8.1) - Random value generation

Infrastructure:

  • MySQL 9.2.0 - Relational database (stacks/platform/modules/dbaas/)
  • PostgreSQL 16.4-bullseye - Primary database with PostGIS/PGVector (stacks/platform/modules/dbaas/)
  • Redis/redis-stack:latest - In-memory cache and broker (stacks/platform/modules/redis/)
  • Headscale 0.23.0 - WireGuard control plane (stacks/platform/modules/headscale/)

Observability:

  • Prometheus - Metrics collection and alerting
  • Grafana - Metrics visualization and dashboards
  • Loki 3.6.5 - Log aggregation (from user instructions)
  • Alloy v1.13.0 - Log collector (from user instructions)

API Gateway & Ingress:

  • Traefik 3.x - Ingress controller and reverse proxy (stacks/platform/modules/traefik/)
  • MetalLB - Load balancer for Kubernetes service IPs (stacks/platform/modules/metallb/)

Security:

  • Authentik - Identity Provider/OIDC (stacks/platform/modules/authentik/)
  • Vaultwarden 1.35.2 - Password manager (stacks/platform/modules/vaultwarden/)
  • CrowdSec - Intrusion detection and IP reputation (stacks/platform/modules/crowdsec/)
  • Kyverno - Policy enforcement and governance (stacks/platform/modules/kyverno/)

Container Images Registry:

  • docker.io - Docker Hub public images
  • ghcr.io - GitHub Container Registry (Headscale UI, Immich, etc.)
  • quay.io - Quay.io registry (inferred from mirror config)
  • registry.k8s.io - Kubernetes images
  • Local pull-through cache at 10.0.20.10 (ports 5000/5010/5020/5030/5040)

Configuration

Environment:

  • terraform.tfvars (git-crypt encrypted) - All secrets, API keys, DNS records, passwords
  • Environment variables injected into Kubernetes pods via ConfigMap/Secret
  • Kubeconfig: config file in repo root (referenced as $PWD/config in terragrunt)

Build:

  • terragrunt.hcl (root) - DRY Terraform provider and backend configuration
  • stacks/<service>/terragrunt.hcl - Per-stack overrides
  • stacks/<service>/main.tf - Kubernetes/Proxmox resource definitions
  • .terraform.lock.hcl - Provider version lock (Terraform 1.x)
  • .terraform/ - Downloaded providers cached locally

Secrets:

  • secrets/ directory (git-crypt encrypted)
  • TLS certificates and keys in secrets/ (symlinked from stacks)
  • OpenDKIM keys for mailserver
  • NFS export configuration in secrets/nfs_directories.txt

Platform Requirements

Development:

  • Terraform 1.x CLI
  • Terragrunt CLI (uses terragrunt apply --non-interactive)
  • kubectl configured with kubeconfig at $PWD/config
  • git-crypt for secret decryption
  • curl, bash, standard Unix utilities

Production:

  • Kubernetes 1.34.2+ cluster (5 nodes, 192 GB+ total memory)
  • Proxmox 8.x hypervisor (stacks/infra/ provisions VMs)
  • NFS storage: TrueNAS at 10.0.10.15 with exports at /mnt/main/
  • Docker registry pull-through cache at 10.0.20.10
  • Cloudflare DNS (public domain viktorbarzin.me)
  • Technitium DNS (internal domain viktorbarzin.lan)

Networking:

  • Kubernetes pod CIDR: managed by cluster
  • Service IPs: 10.0.20.200-10.0.20.220 (MetalLB layer 2)
  • Internal DNS: Technitium at cluster IP
  • External DNS: Cloudflare tunnel + traditional DNS records

Stack analysis: 2026-02-23