Docs rewrite

README.md

@@ -1,33 +1,51 @@
-# 🚀 Proxmox 9 & Linstor HCI Provisioning Pipeline
+# Proxmox 9 & Linstor HCI Provisioning Pipeline
 
-👋 **Welcome!** 
+Declarative Infrastructure as Code pipeline for bootstrapping bare-metal servers into production-ready **Proxmox VE 9 (Debian Trixie)** nodes — either as a 3-node HA cluster with a hyperconverged **Linstor/DRBD** storage stack, or as independent standalone nodes provisioned in parallel.
 
-This repository contains our declarative Infrastructure as Code (IaC) pipeline. It is designed to automatically bootstrap bare-metal servers into production-ready **Proxmox VE 9 (Debian Trixie)** nodes. 
+No local Ansible installation required. The repository ships with a VS Code DevContainer that pins all dependencies.
 
-Whether you are building a 3-node Highly Available cluster with a hyperconverged **Linstor/DRBD** storage stack, or just prepping a dozen independent standalone nodes in parallel, this playbook handles the heavy lifting safely and predictably.
+## Index
 
-## ✨ Features
+1. [Prerequisites & Node Preparation](docs/01-prerequisites.md)
+2. [Configuring the Inventory](docs/02-configuration.md)
+3. [Running the Playbooks](docs/03-execution.md)
+4. [Architecture & Phase Breakdown](docs/04-architecture.md)
+5. [Linstor & Storage Deep Dive](docs/05-linstor-storage.md)
+6. [Troubleshooting & FAQ](docs/06-troubleshooting.md)
 
-* **Zero-Touch Repositories:** Automatically configures modern DEB822 APT sources for Proxmox 9, handles Enterprise licensing per-node, and removes the UI subscription nag.
-* **Smart Reboots:** Detects kernel upgrades (`/var/run/reboot-required`) and safely reboots nodes in the background before forming clusters.
-* **HCI Storage:** Automatically provisions raw block devices into LVM-Thin pools, establishes Corosync clusters, and deploys a highly available Linstor Controller via `drbd-reactor`.
-* **Flexible Topologies:** Easily toggle between full HCI Clusters, External SAN configurations, or completely independent Standalone nodes using simple variables.
+## Repository Layout
 
-## 🏁 Quick Start
+```
+ansible/
+├── deploy.yml                  # Main playbook — full cluster provisioning
+├── network.yml                 # Optional — configure p2p private bridge
+├── ansible.cfg                 # Tuned defaults (pipelining, forks, remote_user)
+├── inventories/
+│   ├── _template/              # Copy this for each new customer/project
+│   │   ├── hosts.ini
+│   │   └── group_vars/all.yml
+│   └── <customer>/             # One inventory per cluster
+├── roles/
+│   ├── p2p_network/            # Configures full-mesh p2p bridge
+│   ├── linstor_repo/           # Adds LINBIT APT repository
+│   ├── linstor_install/        # Installs DRBD, Linstor packages
+│   ├── linstor_cluster/        # Registers nodes, configures /etc/hosts
+│   ├── linstor_ha/             # HA controller via drbd-reactor
+│   ├── linstor_storage/        # LVM thin pools, storage pool registration
+│   └── proxmox_storage/        # Registers Linstor as Proxmox storage backend
+└── docs/
+```
 
-To prevent the classic *"it works on my machine"* problem, this repository is completely self-contained. You do not need to install Ansible or any Python packages on your local computer. 
+## Quick Start
 
-We use a **VS Code DevContainer** that automatically pre-configures your environment with all the correct Ansible versions, collections, and linters.
+```bash
+# 1. Open repo in VS Code DevContainer
+# 2. Copy and configure an inventory
+cp -r ansible/inventories/_template ansible/inventories/<customer>
 
-⏩ **Ready to deploy? Head straight to [Step 01 - Prerequisites](docs/01-prerequisites.md)** to spin up the container and start your first deployment.
+# 3. (Optional) Configure p2p private network bridge
+ansible-playbook ansible/network.yml -i ansible/inventories/<customer>/hosts.ini
 
-## 📚 Documentation Directory
-
-If you are new to Ansible or this specific architecture, please review these guides in order. They are written specifically for our team to ensure safe and consistent deployments across all customer projects.
-
-* 📋 [01 - Prerequisites & Node Preparation](docs/01-prerequisites.md)
-* 🛠️[02 - Configuring the Cluster (Inventory & Vars)](docs/02-configuration.md)
-* ⚡ [03 - Running the Playbook](docs/03-execution.md)
-* 🏗️ [04 - Architecture & Phase Breakdown](docs/04-architecture.md)
-* 💾 [05 - Linstor & Storage Deep Dive](docs/05-linstor-storage.md)
-* 🚑 [06 - Troubleshooting & FAQ](docs/06-troubleshooting.md)
+# 4. Deploy
+ansible-playbook ansible/deploy.yml -i ansible/inventories/<customer>/hosts.ini
+```