Skip to content

docs

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

docs

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
guides
guides
 
 
README.md
README.md
 
 

README.md

📚 Proxmox VE Community Scripts Documentation

Official documentation for using, understanding, developing, and contributing to the Proxmox VE Community Scripts project.

Important

The latest documentation is always published on our website:

https://community-scripts.org/docs

The website is the canonical documentation source. Repository files may represent source content or implementation details, but the published documentation should always be used as the current reference.

🚀 Start Here

Choose the area that best matches what you want to do:

Goal Documentation
Create or understand LXC container scripts Container Scripts
Develop installation scripts Installation Scripts
Create or understand virtual machine scripts VM Scripts
Configure deployments and defaults Configuration Guides
Use management tools and add-ons Tools & Add-ons
Contribute scripts or project changes Contribution Guide
Understand shared Bash libraries Function Libraries
Understand API and telemetry integration API Integration
Study the internal architecture Technical Reference
Troubleshoot an error Exit Codes Reference
Enable development and debugging features Development Mode Guide

📖 Documentation Areas

Container Scripts

Documentation for host-side scripts in ct/ that create and configure Proxmox LXC containers.

Topics include:

  • Container creation flow
  • Script structure and conventions
  • Default and advanced settings
  • Integration with build.func
  • Container and installation script interaction
  • Templates and practical examples

➡️ Open Container Scripts Documentation

Installation Scripts

Documentation for scripts in install/ that run inside containers and install applications.

Topics include:

  • Installation workflow and setup phases
  • Debian, Ubuntu, and Alpine patterns
  • Runtime and database installation
  • Application deployment
  • Configuration and service creation
  • Update and migration logic
  • Integration with helper functions

➡️ Open Installation Scripts Documentation

VM Scripts

Documentation for scripts in vm/ that create QEMU/KVM virtual machines.

Topics include:

  • VM provisioning
  • Cloud-init workflows
  • Image handling
  • Storage and disk configuration
  • Network configuration
  • VM-specific contribution guidance

➡️ Open VM Scripts Documentation

Dev VM scripts use the published Core wizard, storage and lifecycle helpers. Default settings select the standard OS; alternatives belong in Advanced settings or VM_OS_VERSION. Shared Cloud-Init credentials are collected after VM settings for cloud images. Installer ISOs use an independent ISO-capable storage pool, not the VM disk pool.

Native appliances retain their own onboarding: HAOS does not use Cloud-Init, and OpenWrt/OPNsense temporarily boot for configuration even when the final VM_START=no state is requested. A created VM is preserved on subsequent configuration/start failures. VM creation does not imply an ISO installation or a first-boot application setup has finished.

Every vm/*.sh follows one layout and uses Core for the steps that used to be hand-written per script (contract in Core docs/vm.md):

Step Core helper
Banner header_info (generated headers/vm/<slug>; no embedded ASCII art)
Host tools vm_require_tools (no apt-get on the host)
Dialogs vm_dialog and the vm_prompt_* chain (no raw whiptail)
Releases vm_release_asset (GitHub/GitLab/Codeberg, with digest) or vm_latest_from_index (HTML indexes); no hardcoded fallbacks
Download / unpack vm_fetch_image (vendor checksums where published) and vm_extract_image
Image changes vm_prepare_cloud_image, vm_customize, vm_firstboot_unit (run-once units, Cloud-Init aware)
Disk import vm_import_disk and the reported VM_IMPORTED_DISK
Start / address vm_start_vm, vm_wait_for_ip (matched by MAC), vm_wait_http
Closing vm_print_summary, vm_next_steps, vm_finish

vm-wizard-test.sh enforces this layout before it runs the wizard paths.

With Core checked out in .core, run bash .github/workflows/scripts/vm-wizard-test.sh and bash .github/workflows/scripts/vm-lifecycle-test.sh (ONLY="<slug> ..." limits a run to some scripts). CI tests a branch against the Core branch of the same name when one exists, otherwise Core's main. These execute all VM settings paths and mocked creation/start/failure paths; they do not replace real Proxmox boot tests.

Configuration Guides

Guides for configuring and automating Community Scripts deployments.

Topics include:

  • Configuration variables
  • Default settings
  • Per-script overrides
  • Storage and network configuration
  • Unattended deployments
  • Environment-variable-based provisioning
  • Incus host setup (unified ct/ scripts on Incus)
  • Script origin (fork/branch) (local checkout + remote run.sh)

➡️ Open Configuration Guides

Tools & Add-ons

Documentation for Proxmox VE management utilities, administration helpers, and optional add-ons.

➡️ Open Tools & Add-ons Documentation

Function Libraries

Technical documentation for the shared Bash libraries, which live in community-scripts/core.

The documented libraries include:

  • core/build.func
  • core/core.func
  • core/error_handler.func
  • api/api.func
  • lxc/install.func
  • lib/tools.func
  • lxc/alpine-install.func
  • lib/alpine.func
  • vm/cloud-init.func

The documentation explains individual functions, dependencies between libraries, execution flows, error handling, telemetry, logging, package management, and provisioning behavior.

➡️ Open Function Libraries Documentation

API Integration

Documentation for the website API, telemetry services, diagnostics, metadata handling, and related integration points.

➡️ Open API Documentation

🤝 Contributing

The contribution documentation contains the current requirements, templates, coding standards, and review guidance for submitting changes.

Main resources

Before submitting a pull request:

  1. Read the current contribution guide.
  2. Review the relevant script documentation.
  3. Start from an official template where available.
  4. Compare your implementation with similar existing scripts.
  5. Test the complete creation, installation, update, and error-handling flow.

🛠 Troubleshooting

For failed installations or unexpected behavior, start with:

  1. Exit Codes Reference
  2. Development Mode Guide
  3. Function Libraries
  4. The documentation for the affected script type

When reporting an issue, include:

  • Proxmox VE version
  • Script name
  • Exact command used
  • Complete error output
  • Exit code
  • Relevant debug or verbose logs
  • Whether default or advanced settings were used

🏗 Technical Reference

Advanced implementation details are documented separately:

These sections cover architecture, configuration precedence, execution flow, helper-library relationships, telemetry, error handling, and development internals.

🔍 Search the Documentation

The documentation website provides full-text search.

Open:

https://community-scripts.org/docs

Then use the search field or press:

  • Ctrl + K on Windows and Linux
  • ⌘ + K on macOS

📝 Documentation Updates

Documentation is maintained continuously and published through the central documentation website.

Do not rely on hard-coded document counts, line counts, version labels, completeness percentages, or last-updated dates in this README. These values become outdated quickly and do not represent the current state of the published documentation.

For the latest content, navigation, examples, and references, always use:

https://community-scripts.org/docs

💬 Support and Feedback

Found an error or missing information?

Proxmox VE Community Scripts Documentation

Open Documentation · View Scripts · Contribute