mirror of
https://github.com/community-scripts/ProxmoxVE.git
synced 2026-02-06 05:13:27 +01:00
cb939861b8
* Enhance setup-fork.sh with --full mode and misc/ targeting Added a new --full flag to setup-fork.sh to allow updating all files, not just those in misc/. Updated documentation and usage examples to clarify the new behavior. Improved file search and replacement logic for broader compatibility and flexibility. * add AI.md * fix links in AI.md * Update contribution docs and templates for best practices Refreshed AI.md with new reference scripts, expanded checklist, and improved AI assistant tips. Updated container and install script templates for modern defaults (Debian 13, larger disk, two tags), clarified helper function usage, and improved update/backup patterns. Enhanced JSON template with realistic metadata, new fields, and example notes. * Update fetch_and_deploy_gh_release usage in docs and templates Standardize the usage of fetch_and_deploy_gh_release by specifying all arguments, including mode, version, and target directory, in AI.md and template scripts. This clarifies the function's usage and ensures consistency across documentation and install/update templates. * Revise contribution docs and update CT template Expanded and clarified contribution documentation for forking, local development, cherry-picking, and AI-assisted code generation. Improved explanations for setup-fork.sh, local testing, and PR submission. Enhanced the container script template with detailed comments, clearer update_script structure, and step-by-step guidance for maintainers and contributors. * Update fork and release instructions in contribution docs Replaced placeholder GitHub repo references with 'YourUsername/YourRepo' throughout documentation for clarity. Expanded explanations in FORK_SETUP.md and README.md to clarify the difference between development and production script execution, and emphasized the importance of cherry-picking only relevant files for PRs. Updated install script template examples to use the new repo placeholder. * Update GitHub repo placeholders in docs and templates Replaced 'YourUsername/YourRepo' with 'owner/repo' in documentation and template scripts for consistency and clarity. This change standardizes example usage and reduces confusion for contributors. * Move user submitted guides to guides directory Renamed USER_SUBMITTED_GUIDES.md from docs/contribution to docs/guides for improved documentation organization. * Update contribution docs for improved workflow and clarity Revised multiple documentation files to clarify the recommended development workflow: contributors must test scripts via curl from their GitHub fork (not local bash), use setup-fork.sh for URL rewriting, and submit only new files using cherry-pick. Expanded and modernized install and JSON metadata template guides, emphasizing use of helper functions, resource requirements, and the JSON generator tool. Added detailed step-by-step instructions, best practices, and updated examples throughout. * Update contribution docs for new file structure Updated documentation to reflect the migration of install scripts from install_scripts/ to install/, and JSON metadata from config/ to frontend/public/json/. Adjusted all relevant paths, instructions, and examples to match the new directory structure for improved clarity and consistency. * Update contribution docs for fork setup and metadata Revised documentation to standardize use of 'bash docs/contribution/setup-fork.sh --full' for fork configuration, clarified install script execution flow, and updated JSON metadata template and field references. Improved helper function docs, resource requirements, and category lists. Updated references and instructions throughout for consistency and accuracy. * Docs: add GPU/TUN, update endpoints & tool refs Documentation updates across guides and function references: - Added var_gpu and var_tun configuration entries to CONFIGURATION_REFERENCE (GPU passthrough and TUN/TAP support), including features and prerequisites. - Fixed repository URLs throughout UNATTENDED_DEPLOYMENTS and examples: replaced community-scripts/ProxmoxVED with community-scripts/ProxmoxVE and updated curl usage to the new paths. - Added an "Advanced Configuration Variables" table and examples (var_os, var_version, var_gpu, var_tun, var_nesting) to UNATTENDED_DEPLOYMENTS; adjusted sample apps, hostnames, and container mappings in batch examples. - Switched API endpoints in API_FUNCTIONS_REFERENCE and API_USAGE_EXAMPLES from http://api.community-scripts.org to https://api.community-scripts.org. - Expanded BUILD_FUNC_FUNCTIONS_REFERENCE with container resource/ID management helper descriptions (validate_container_id, get_valid_container_id, maxkeys_check, get_current_ip, update_motd_ip). - Large edits to TOOLS_FUNC_FUNCTIONS_REFERENCE: renamed/refactored helper signatures and docs (pkg_install -> install_packages_with_retry, pkg_update -> upgrade_packages_with_retry), added new tooling functions (fetch_and_deploy_gh_release, check_for_gh_release, prepare_repository_setup, verify_tool_version) and updated examples and feature notes. - Updated vm/README.md to list additional VM scripts (new and reorganized examples). These are documentation-only changes to clarify configuration options, correct links and endpoints, and expand the reference material for tooling and build helpers. * Docs: expand developer/debugging and tools references Add extensive documentation and examples across contribution, guides, templates and tools references. Key changes: - Introduce a Developer Mode & Debugging section (dev_mode flags: trace, keep, pause, breakpoint, logs, dryrun, motd) in CONTRIBUTING.md with usage example. - Provide a standard update_script() pattern and BookStack example in GUIDE.md to clarify update flow (stop services, backup, deploy, restore, migrate, restart). - Add new helper entries (BookLore, KaraKeep) and advanced repository helpers (setup_deb822_repo, prepare_repository_setup, cleanup_tool_keyrings) plus utilities (setup_meilisearch, verify_tool_version) in HELPER_FUNCTIONS.md. - Update install template to suggest PNPM, Java 21 and Meilisearch; update example DB setup notes in AppName-install.sh. - Add var_diagnostics option and switch var_fuse to boolean/toggle wording in CONFIGURATION_REFERENCE.md; clarify privacy and defaults. - Adjust example container definitions in UNATTENDED_DEPLOYMENTS.md (container entries and resource values). - Change storage and flag variables and examples in BUILD_FUNC_USAGE_EXAMPLES.md (ssd-storage, var_fuse/var_tun, etc.). - Expand TOOLS_FUNC_FUNCTIONS_REFERENCE.md with many setup_* function signatures, environment vars, clarified fetch_and_deploy_gh_release modes/parameters, and additional tool docs (nodejs, php, mariadb_db, postgresql_db, java, uv, yq, meilisearch, composer, build tools). These updates improve onboarding, debugging guidance, and operational clarity for contributors and maintainers.
📚 ProxmoxVE Documentation
Complete guide to all ProxmoxVE 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: guides/DEFAULTS_SYSTEM_GUIDE.md
Deploy containers automatically → Read: guides/UNATTENDED_DEPLOYMENTS.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: guides/DEFAULTS_SYSTEM_GUIDE.md → Automate: guides/UNATTENDED_DEPLOYMENTS.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:
ProxmoxVE/
├─ 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)
└─ [system-wide] ↔ docs/guides/ (configuration & deployment guides)
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 |
| guides/DEFAULTS_SYSTEM_GUIDE.md | Configuration system | Operators, power users |
| guides/CONFIGURATION_REFERENCE.md | Configuration options reference | Advanced users |
| guides/UNATTENDED_DEPLOYMENTS.md | Automated deployments | DevOps, automation |
| EXIT_CODES.md | Exit code reference | Troubleshooters |
| DEV_MODE.md | Debugging tools | Developers |
📂 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)
- contribution/README.md - Quick Start
- Pick your area:
- Containers → ct/README.md + ct/DETAILED_GUIDE.md
- Installation → install/README.md + install/DETAILED_GUIDE.md
- VMs → vm/README.md
- Study existing similar script
- Create your contribution
- Submit PR
Path 2: Intermediate Developer (4-6 hours)
- TECHNICAL_REFERENCE.md
- Dive into function libraries:
- Study advanced examples
- Create complex applications
Path 3: Advanced Architect (8+ hours)
- All of Intermediate Path
- Study all 9 function libraries in depth
- guides/DEFAULTS_SYSTEM_GUIDE.md - Configuration system
- DEV_MODE.md - Debugging and development
- Design new features or function libraries
Path 4: Troubleshooter (30 minutes - 1 hour)
- EXIT_CODES.md - Find error code
- DEV_MODE.md - Run with debugging
- Check relevant function library docs
- 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 → guides/DEFAULTS_SYSTEM_GUIDE.md
- Automation → guides/UNATTENDED_DEPLOYMENTS.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 ProxmoxVE? → 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?
- See: contribution/README.md for full contribution guide
- Open issue: GitHub Issues
- 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 ProxmoxVE! Start with CONTRIBUTION_GUIDE.md or choose your role above. 🚀