From de90bbb333ea93e7a5dc371ddc25b6a365619aed Mon Sep 17 00:00:00 2001 From: Stanislav Hubacek Date: Sun, 12 Apr 2026 21:48:43 +0200 Subject: [PATCH] Delete README.md --- README.md | 547 ------------------------------------------------------ 1 file changed, 547 deletions(-) delete mode 100644 README.md diff --git a/README.md b/README.md deleted file mode 100644 index 143dd94..0000000 --- a/README.md +++ /dev/null @@ -1,547 +0,0 @@ -# Homelab Provisioning Portal — MVP Spec - -## Goal -A small internal web application that lets me provision Proxmox LXC containers and selected VMs through a simple web form, then optionally integrate them into my existing homelab workflow: - -- Proxmox provisioning -- initial package/profile setup -- Git-backed Caddy config generation -- optional DNS integration -- optional monitoring integration - -The portal is not meant to be a generic public PaaS. It is an internal operator tool for a controlled homelab environment. - ---- - -## Core principles - -### 1. GUI for input, API-driven execution -The user experience should be a simple web form, but the backend should orchestrate everything through APIs, scripts, and structured jobs. - -### 2. Profiles over chaos -Instead of exposing every package and configuration toggle directly, the app should use a small number of workload profiles. - -### 3. Git as source of truth where possible -Reverse proxy configuration should not be edited directly. The portal should write service definitions into the Git repo and let the existing deployment pipeline handle Caddy. - -### 4. Jobs, not blocking requests -Provisioning should run as background jobs with visible status, logs, and clear success/failure states. - -### 5. Safe defaults -The portal should prefer prevalidated combinations of: -- node -- storage -- template -- network mode -- package sets -- exposure rules - ---- - -## MVP scope - -### In scope -- create LXC containers -- create from a selected profile -- set hostname, CPU, RAM, disk, node, storage, network mode -- optional static IP or DHCP -- optional package installation through profile provisioning -- optional generation of Caddy service YAML in Git repo -- job history and logs - -### Out of scope for MVP -- full VM lifecycle -- Terraform integration -- approvals/workflows -- user accounts / RBAC beyond a single trusted operator -- advanced DNS API automation -- full secrets management UI -- rollback orchestration across all systems - ---- - -## Profiles for MVP - -### 1. Static Website -Purpose: -- simple web presentations / landing pages / personal sites - -Provisioning: -- Debian LXC -- nginx or apache installed -- document root prepared -- optional domain -- optional Caddy service YAML generated - -### 2. Generic Service -Purpose: -- small internal services - -Provisioning: -- Debian LXC -- base utilities -- optional Docker -- optional node exporter -- no public exposure by default - -### 3. Monitoring Node -Purpose: -- internal monitoring or utility workloads - -Provisioning: -- Debian LXC -- node exporter -- curl / git / basic tools -- no public exposure by default - -### 4. Web App -Purpose: -- internal or public HTTP application - -Provisioning: -- Debian LXC -- web server or runtime preset -- optional Caddy service YAML -- optional health endpoint setting stored in service definition - ---- - -## User flow - -### Step 1 — Choose workload type -- LXC -- VM (disabled or marked as coming later in MVP) - -### Step 2 — Choose profile -- Static Website -- Generic Service -- Monitoring Node -- Web App - -### Step 3 — Basic settings -- hostname -- description -- target node -- storage -- CPU cores -- RAM (MB) -- disk size (GB) -- start after creation (yes/no) - -### Step 4 — Network -- DHCP / Static IP -- static IP address (if selected) -- gateway (optional) -- bridge -- VLAN tag (optional) - -### Step 5 — Service integration -- domain name (optional) -- expose via Caddy (yes/no) -- public or internal service -- enable monitoring (yes/no) - -### Step 6 — Review -Show: -- chosen node -- chosen profile -- resources -- network settings -- generated service definition preview if relevant -- list of post-provision actions - -### Step 7 — Create job -- portal stores job -- worker executes it -- UI shows progress and logs - ---- - -## Proposed architecture - -## Frontend -Simple server-rendered UI. - -Recommended: -- FastAPI + Jinja templates -- minimal JS only where needed - -Why: -- lightweight -- easy to deploy in LXC -- low maintenance -- fast iteration - -## Backend -FastAPI application with: -- form handling -- validation -- job creation -- background execution -- job log viewing - -## Persistence -SQLite for MVP. - -Tables: -- jobs -- job_logs -- profiles -- created_resources (optional for tracking) - -## Execution layer -The backend should call a dedicated internal execution layer, not shell out from route handlers directly. - -Modules: -- proxmox.py -- gitops.py -- provision.py -- jobs.py -- models.py - ---- - -## Backend modules - -### proxmox.py -Responsibilities: -- create LXC -- optionally start LXC -- poll for completion -- retrieve created CTID / details - -Possible implementation paths: -- Proxmox API directly -- wrapper around `pct` CLI if app runs on a trusted node - -Recommendation: -- use Proxmox API for long-term cleanliness -- CLI wrapper acceptable for MVP if simpler in your environment - -### provision.py -Responsibilities: -- post-create setup inside container -- install profile packages -- prepare directories -- optionally write default nginx/apache config - -Implementation options: -- SSH / pct exec -- Ansible later - -Recommendation for MVP: -- use `pct exec` from a trusted node if the app runs close to Proxmox -- move to Ansible later if desired - -### gitops.py -Responsibilities: -- write service YAML definitions into repo -- validate generated content -- git add / commit / push - -Important: -- this module should only touch approved repo paths -- no arbitrary file writes from user input - -### jobs.py -Responsibilities: -- create job records -- store state transitions -- append logs -- expose job status to UI - -States: -- pending -- running -- succeeded -- failed - ---- - -## Data model (MVP) - -### Job -- id -- created_at -- started_at -- finished_at -- type -- profile -- payload_json -- status -- summary -- result_json -- error_message - -### JobLog -- id -- job_id -- timestamp -- level -- message - -### ProfileDefinition -Can be hardcoded initially or stored in code/YAML. - -Suggested profile fields: -- name -- description -- supported_kind -- default_packages -- allow_public_exposure -- allow_domain -- default_web_server -- post_create_actions - ---- - -## Validation rules - -### General -- hostname required, restricted format -- RAM / disk / CPU must be from allowed ranges -- node must be from approved node list -- storage must be from approved storage list -- profile must be from approved profile list - -### Network -- if static IP selected, IP must be valid -- optional uniqueness check against known reserved IPs - -### Domain/Caddy -- if expose via Caddy is enabled, domain required -- domain uniqueness check against existing service definitions -- backend IP generated from created container, not manually trusted from form - -### Safety -- never accept arbitrary shell commands from UI -- never allow arbitrary package strings in MVP -- use whitelisted package sets by profile - ---- - -## Caddy integration design - -When a workload is marked as web-exposed, the portal should generate a service YAML in the existing homelab repo. - -Example output: - -```yaml -name: app.example.com -type: proxy -domain: app.example.com -headers: true -auth: false -backend: 192.168.50.210:80 -``` - -For static website profile with an app server in the container, use proxy mode as well, since the architecture should keep services containerized. - -Portal should then: -1. write YAML -2. git add / commit / push -3. rely on existing Git webhook deployment to update Caddy - ---- - -## Monitoring integration - -For MVP, monitoring integration can be lightweight. - -Options: -- install node exporter in container for selected profiles -- add a label/tag to the resource for later tracking -- optionally note in job result whether monitoring was enabled - -Prometheus target automation can come later unless you already have a standard discovery mechanism. - ---- - -## UI pages for MVP - -### 1. Dashboard -- recent jobs -- quick create button -- summary counts - -### 2. New workload form -- multi-step or grouped single-page form - -### 3. Job detail page -- job status -- timestamps -- execution logs -- generated outputs - -### 4. Profiles page (optional) -- read-only overview of supported profiles - ---- - -## Recommended tech stack - -### App runtime -- Python 3 -- FastAPI -- Jinja2 -- SQLite -- Uvicorn - -### Optional frontend enhancement -- HTMX for better UX without building a full SPA - -### Deployment target -- dedicated LXC container -- internal-only exposure via Caddy or VPN - ---- - -## Security model - -### Access -- internal-only -- preferably behind VPN or internal-only reverse proxy - -### Secrets -Keep these outside Git: -- Proxmox API token -- Gitea token or SSH deploy key -- optional DNS API tokens - -Use environment file or systemd environment variables. - -### Permissions -Use a restricted Proxmox API token rather than root password where possible. - ---- - -## What needs to be prepared first - -## A. Proxmox preparation -- choose whether MVP uses API or local CLI -- prepare at least one approved LXC template -- define approved nodes -- define approved storage targets -- define approved network bridge(s) -- define CTID strategy (manual range or automatic lookup) - -## B. Git / Caddy preparation -- confirm repo path and branch for service definitions -- confirm exact YAML schema used by current generator -- define naming convention for generated files -- define whether portal commits directly to main or a staging branch - -## C. Host/container provisioning preparation -- decide which base OS template to use for LXC -- define profile package lists -- define default web server choice (nginx or apache) -- decide whether provisioning happens through `pct exec` or SSH - -## D. App hosting preparation -- create dedicated LXC for the portal -- internal DNS name, e.g. `portal.hubacek.cloud` -- internal-only reverse proxy rule -- prepare environment file for secrets - ---- - -## Concrete preparation checklist - -### 1. Decide execution method -Choose one: -- Proxmox API only -- Proxmox API for create + `pct exec` for post-provision -- local CLI wrapper (`pct`, `qm`) if app runs on a Proxmox node - -Recommended MVP: -- Proxmox API for create -- `pct exec` for post-provision if app runs on a trusted node - -### 2. Define profile presets -Prepare final values for: -- Static Website -- Generic Service -- Monitoring Node -- Web App - -For each profile define: -- template -- packages -- default ports -- whether Caddy integration is allowed -- whether monitoring is installed - -### 3. Define allowed infrastructure values -Prepare lists for: -- nodes -- storage -- bridges -- VLAN choices if any -- RAM options -- disk options -- CPU options - -### 4. Prepare secrets -Need: -- Proxmox API token -- Gitea credential/token or deploy key - -### 5. Decide repo write behavior -Options: -- portal commits directly to main -- portal writes a branch and you merge manually - -Recommended MVP: -- direct commit to main if only you use it - ---- - -## Proposed MVP implementation order - -### Phase 1 -- app skeleton -- SQLite job model -- create LXC with Generic Service profile -- show job logs - -### Phase 2 -- add Static Website and Web App profiles -- add package installation / post-provision steps -- add Caddy Git integration - -### Phase 3 -- add Monitoring profile -- add better job output and validation -- add optional DNS integration - -### Phase 4 -- add VM workflow -- add cloud-init templates -- add role-based access or approvals if ever needed - ---- - -## Immediate next actions - -1. Finalize execution strategy -2. Finalize profile definitions -3. Finalize allowed infrastructure options -4. Create dedicated portal container -5. Add Proxmox and Gitea credentials outside Git -6. Build MVP backend skeleton - ---- - -## Recommended execution strategy for your homelab - -For your current setup, the most practical MVP is: - -- portal app in dedicated LXC -- internal-only exposure -- Proxmox API for provisioning -- Git repo write for Caddy service definitions -- existing webhook pipeline deploys proxy config -- post-provision through trusted remote execution later, if not in MVP day one - -This keeps the system aligned with what you already have working instead of replacing it. -