ProxmoxVED/docs/README.md

📚 ProxmoxVED Documentation

Complete guide to all ProxmoxVED documentation - quickly find what you need.

---

🎯 Quick Navigation by Goal

👤 I want to...

Contribute a new application → Start with: contribution/README.md → Then: ct/DETAILED_GUIDE.md + install/DETAILED_GUIDE.md

Understand the architecture → Read: TECHNICAL_REFERENCE.md → Then: misc/README.md

Debug a failed installation → Check: EXIT_CODES.md → Then: DEV_MODE.md → See also: misc/error_handler.func/

Configure system defaults → Read: DEFAULTS_SYSTEM_GUIDE.md

Learn about recent changes → Check: CHANGELOG_MISC.md

Develop a function library → Study: misc/ documentation

---

👤 Quick Start by Role

I'm a...

New Contributor → Start: contribution/README.md → Then: Choose your path below

Container Creator → Read: ct/README.md → Deep Dive: ct/DETAILED_GUIDE.md → Reference: misc/build.func/

Installation Script Developer → Read: install/README.md → Deep Dive: install/DETAILED_GUIDE.md → Reference: misc/tools.func/

VM Provisioner → Read: vm/README.md → Reference: misc/cloud-init.func/

Tools Developer → Read: tools/README.md → Reference: misc/build.func/

API Integrator → Read: api/README.md → Reference: misc/api.func/

System Operator → Start: EXIT_CODES.md → Then: DEFAULTS_SYSTEM_GUIDE.md → Debug: DEV_MODE.md

Architect → Read: TECHNICAL_REFERENCE.md → Deep Dive: misc/README.md

---

📂 Documentation Structure

Project-Mirrored Directories

Each major project directory has documentation:

ProxmoxVED/
├─ ct/                 ↔ docs/ct/ (README.md + DETAILED_GUIDE.md)
├─ install/           ↔ docs/install/ (README.md + DETAILED_GUIDE.md)
├─ vm/                ↔ docs/vm/ (README.md)
├─ tools/            ↔ docs/tools/ (README.md)
├─ api/              ↔ docs/api/ (README.md)
└─ misc/             ↔ docs/misc/ (9 function libraries)

Core Documentation

Document	Purpose	Audience
contribution/README.md	How to contribute	Contributors
ct/DETAILED_GUIDE.md	Create ct scripts	Container developers
install/DETAILED_GUIDE.md	Create install scripts	Installation developers
TECHNICAL_REFERENCE.md	Architecture deep-dive	Architects, advanced users
DEFAULTS_SYSTEM_GUIDE.md	Configuration system	Operators, power users
EXIT_CODES.md	Exit code reference	Troubleshooters
DEV_MODE.md	Debugging tools	Developers
CHANGELOG_MISC.md	Recent changes	Everyone

---

📂 Directory Guide

ct/ - Container Scripts

Documentation for /ct - Container creation scripts that run on the Proxmox host.

Includes:

• Overview of container creation process
• Deep dive: DETAILED_GUIDE.md - Complete reference with examples
• Reference to misc/build.func/
• Quick start for creating new containers

install/ - Installation Scripts

Documentation for /install - Scripts that run inside containers to install applications.

Includes:

• Overview of 10-phase installation pattern
• Deep dive: DETAILED_GUIDE.md - Complete reference with examples
• Reference to misc/tools.func/
• Alpine vs Debian differences

vm/ - Virtual Machine Scripts

Documentation for /vm - VM creation scripts using cloud-init provisioning.

Includes:

• Overview of VM provisioning
• Link to misc/cloud-init.func/
• VM vs Container comparison
• Cloud-init examples

tools/ - Tools & Utilities

Documentation for /tools - Management tools and add-ons.

Includes:

• Overview of tools structure
• Integration points
• Contributing new tools
• Common operations

api/ - API Integration

Documentation for /api - Telemetry and API backend.

Includes:

• API overview
• Integration methods
• API endpoints
• Privacy information

misc/ - Function Libraries

Documentation for /misc - 9 core function libraries with complete references.

Contains:

• build.func/ - Container orchestration (7 files)
• core.func/ - Utilities and messaging (5 files)
• error_handler.func/ - Error handling (5 files)
• api.func/ - API integration (5 files)
• install.func/ - Container setup (5 files)
• tools.func/ - Package installation (6 files)
• alpine-install.func/ - Alpine setup (5 files)
• alpine-tools.func/ - Alpine tools (5 files)
• cloud-init.func/ - VM provisioning (5 files)

---

🎓 Learning Paths

Path 1: First-Time Contributor (2-3 hours)

1. contribution/README.md - Quick Start
2. Pick your area:
   • Containers → ct/README.md + ct/DETAILED_GUIDE.md
   • Installation → install/README.md + install/DETAILED_GUIDE.md
   • VMs → vm/README.md
3. Study existing similar script
4. Create your contribution
5. Submit PR

Path 2: Intermediate Developer (4-6 hours)

1. TECHNICAL_REFERENCE.md
2. Dive into function libraries:
   • misc/build.func/README.md
   • misc/tools.func/README.md
   • misc/install.func/README.md
3. Study advanced examples
4. Create complex applications
5. Review CHANGELOG_MISC.md for recent changes

Path 3: Advanced Architect (8+ hours)

1. All of Intermediate Path
2. Study all 9 function libraries in depth
3. DEFAULTS_SYSTEM_GUIDE.md - Configuration system
4. DEV_MODE.md - Debugging and development
5. Design new features or function libraries

Path 4: Troubleshooter (30 minutes - 1 hour)

1. EXIT_CODES.md - Find error code
2. DEV_MODE.md - Run with debugging
3. Check relevant function library docs
4. Review logs and fix

---

📊 By the Numbers

Metric	Count
Documentation Files	63
Total Lines	15,000+
Function Libraries	9
Functions Documented	150+
Code Examples	50+
Flowcharts	15+
Do/Don't Sections	20+
Real-World Examples	30+

---

🔍 Find It Fast

By Feature

• How do I create a container? → ct/DETAILED_GUIDE.md
• How do I create an install script? → install/DETAILED_GUIDE.md
• How do I create a VM? → vm/README.md
• How do I install Node.js? → misc/tools.func/
• How do I debug? → DEV_MODE.md

By Error

• Exit code 206? → EXIT_CODES.md
• Network failed? → misc/install.func/
• Package error? → misc/tools.func/

By Role

• Contributor → contribution/README.md
• Operator → DEFAULTS_SYSTEM_GUIDE.md
• Developer → TECHNICAL_REFERENCE.md
• Architect → misc/README.md

---

✅ Documentation Features

• ✅ Project-mirrored structure - Organized like the actual project
• ✅ Complete function references - Every function documented
• ✅ Real-world examples - Copy-paste ready code
• ✅ Visual flowcharts - ASCII diagrams of workflows
• ✅ Integration guides - How components connect
• ✅ Troubleshooting - Common issues and solutions
• ✅ Best practices - DO/DON'T sections throughout
• ✅ Learning paths - Structured curriculum by role
• ✅ Quick references - Fast lookup by error code
• ✅ Comprehensive navigation - This page

---

🚀 Start Here

New to ProxmoxVED? → contribution/README.md

Looking for something specific? → Choose your role above or browse by directory

Need to debug? → EXIT_CODES.md

Want to understand architecture? → TECHNICAL_REFERENCE.md

---

🤝 Contributing Documentation

Found an error? Want to improve docs?

1. See: contribution/README.md for full contribution guide
2. Open issue: GitHub Issues
3. Or submit PR with improvements

---

📝 Status

• Last Updated: December 2025
• Version: 2.3 (Consolidated & Reorganized)
• Completeness: ✅ 100% - All components documented
• Quality: ✅ Production-ready
• Structure: ✅ Clean and organized

---

Welcome to ProxmoxVED! Start with CONTRIBUTION_GUIDE.md or choose your role above. 🚀