nexus/ProxmoxVE
2
0
Fork 0
mirror of https://github.com/community-scripts/ProxmoxVE.git synced 2026-04-18 16:32:17 +00:00
Code Issues Packages Projects Releases Wiki Activity

github: extend docs / contribution / templates (#10921)

Browse Source 
* 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.
This commit is contained in:
CanbiZ (MickLesk)
2026-02-05 16:45:41 +01:00
committed by GitHub
parent c576728833
commit cb939861b8
23 changed files with 2906 additions and 740 deletions
Download Patch File Download Diff File Expand all files Collapse all files

179
docs/contribution/HELPER_FUNCTIONS.md
View File

@@ -30,61 +30,79 @@
> ⚠️ **Both files are ALWAYS required!** The CT script calls the install script automatically during container creation.
Install scripts are **not** run directly by users; they are invoked by the CT script inside the container.
### Node.js + PostgreSQL
**Koel** - Music streaming with PHP + Node.js + PostgreSQL
| File | Link |
| File | Link |
| ----------------- | -------------------------------------------------------- |
| CT (update logic) | [ct/koel.sh](../../ct/koel.sh) |
| Install | [install/koel-install.sh](../../install/koel-install.sh) |
| CT (update logic) | [ct/koel.sh](../../ct/koel.sh) |
| Install | [install/koel-install.sh](../../install/koel-install.sh) |
**Actual Budget** - Finance app with npm global install
| File | Link |
| File | Link |
| ----------------- | ------------------------------------------------------------------------ |
| CT (update logic) | [ct/actualbudget.sh](../../ct/actualbudget.sh) |
| Install | [install/actualbudget-install.sh](../../install/actualbudget-install.sh) |
| CT (update logic) | [ct/actualbudget.sh](../../ct/actualbudget.sh) |
| Install | [install/actualbudget-install.sh](../../install/actualbudget-install.sh) |
### Python + uv
**MeTube** - YouTube downloader with Python uv + Node.js + Deno
| File | Link |
| File | Link |
| ----------------- | ------------------------------------------------------------ |
| CT (update logic) | [ct/metube.sh](../../ct/metube.sh) |
| Install | [install/metube-install.sh](../../install/metube-install.sh) |
| CT (update logic) | [ct/metube.sh](../../ct/metube.sh) |
| Install | [install/metube-install.sh](../../install/metube-install.sh) |
**Endurain** - Fitness tracker with Python uv + PostgreSQL/PostGIS
| File | Link |
| File | Link |
| ----------------- | ---------------------------------------------------------------- |
| CT (update logic) | [ct/endurain.sh](../../ct/endurain.sh) |
| Install | [install/endurain-install.sh](../../install/endurain-install.sh) |
| CT (update logic) | [ct/endurain.sh](../../ct/endurain.sh) |
| Install | [install/endurain-install.sh](../../install/endurain-install.sh) |
### Java + Gradle
**BookLore** - Book management with Java 21 + Gradle + MariaDB + Nginx
| File | Link |
| ----------------- | -------------------------------------------------------------- |
| CT (update logic) | [ct/booklore.sh](../../ct/booklore.sh) |
| Install | [install/booklore-install.sh](../../install/booklore-install.sh) |
### Pnpm + Meilisearch
**KaraKeep** - Bookmark manager with Pnpm + Meilisearch + Puppeteer
| File | Link |
| ----------------- | -------------------------------------------------------------- |
| CT (update logic) | [ct/karakeep.sh](../../ct/karakeep.sh) |
| Install | [install/karakeep-install.sh](../../install/karakeep-install.sh) |
### PHP + MariaDB/MySQL
**Wallabag** - Read-it-later with PHP + MariaDB + Redis + Nginx
| File | Link |
| File | Link |
| ----------------- | ---------------------------------------------------------------- |
| CT (update logic) | [ct/wallabag.sh](../../ct/wallabag.sh) |
| Install | [install/wallabag-install.sh](../../install/wallabag-install.sh) |
| CT (update logic) | [ct/wallabag.sh](../../ct/wallabag.sh) |
| Install | [install/wallabag-install.sh](../../install/wallabag-install.sh) |
**InvoiceNinja** - Invoicing with PHP + MariaDB + Supervisor
| File | Link |
| File | Link |
| ----------------- | ------------------------------------------------------------------------ |
| CT (update logic) | [ct/invoiceninja.sh](../../ct/invoiceninja.sh) |
| Install | [install/invoiceninja-install.sh](../../install/invoiceninja-install.sh) |
| CT (update logic) | [ct/invoiceninja.sh](../../ct/invoiceninja.sh) |
| Install | [install/invoiceninja-install.sh](../../install/invoiceninja-install.sh) |
**BookStack** - Wiki/Docs with PHP + MariaDB + Apache
| File | Link |
| File | Link |
| ----------------- | ------------------------------------------------------------------ |
| CT (update logic) | [ct/bookstack.sh](../../ct/bookstack.sh) |
| Install | [install/bookstack-install.sh](../../install/bookstack-install.sh) |
| CT (update logic) | [ct/bookstack.sh](../../ct/bookstack.sh) |
| Install | [install/bookstack-install.sh](../../install/bookstack-install.sh) |
### PHP + SQLite (Simple)
**Speedtest Tracker** - Speedtest with PHP + SQLite + Nginx
| File | Link |
| File | Link |
| ----------------- | ---------------------------------------------------------------------------------- |
| CT (update logic) | [ct/speedtest-tracker.sh](../../ct/speedtest-tracker.sh) |
| Install | [install/speedtest-tracker-install.sh](../../install/speedtest-tracker-install.sh) |
| CT (update logic) | [ct/speedtest-tracker.sh](../../ct/speedtest-tracker.sh) |
| Install | [install/speedtest-tracker-install.sh](../../install/speedtest-tracker-install.sh) |
---
@@ -95,7 +113,7 @@
Install Node.js from NodeSource repository.
```bash
# Default (Node.js 22)
# Default (Node.js 24)
setup_nodejs
# Specific version
@@ -135,8 +153,12 @@ $STD cargo build --release
Install Python uv package manager (fast pip/venv replacement).
```bash
# Default
setup_uv
# Install a specific Python version
PYTHON_VERSION="3.12" setup_uv
# Use in script
setup_uv
cd /opt/myapp
@@ -160,7 +182,7 @@ Install PHP with configurable modules and FPM/Apache support.
setup_php
# Full configuration
PHP_VERSION="8.3" \
PHP_VERSION="8.4" \
PHP_MODULE="mysqli,gd,curl,mbstring,xml,zip,ldap" \
PHP_FPM="YES" \
PHP_APACHE="YES" \
@@ -168,12 +190,12 @@ setup_php
```
**Environment Variables:**
| Variable | Default | Description |
| Variable | Default | Description |
| ------------- | ------- | ------------------------------- |
| `PHP_VERSION` | `8.3` | PHP version to install |
| `PHP_MODULE` | `""` | Comma-separated list of modules |
| `PHP_FPM` | `NO` | Install PHP-FPM |
| `PHP_APACHE` | `NO` | Install Apache module |
| `PHP_VERSION` | `8.4` | PHP version to install |
| `PHP_MODULE` | `""` | Comma-separated list of modules |
| `PHP_FPM` | `NO` | Install PHP-FPM |
| `PHP_APACHE` | `NO` | Install Apache module |
### `setup_composer`
@@ -239,12 +261,12 @@ setup_mysql
Install PostgreSQL server.
```bash
# Default (PostgreSQL 17)
# Default (PostgreSQL 16)
setup_postgresql
# Specific version
PG_VERSION="16" setup_postgresql
PG_VERSION="17" setup_postgresql
PG_VERSION="16" setup_postgresql
```
### `setup_postgresql_db`
@@ -279,6 +301,43 @@ setup_clickhouse
---
## Advanced Repository Management
### `setup_deb822_repo`
The modern standard (Debian 12+) for adding external repositories. Automatically handles GPG keys and sources.
```bash
setup_deb822_repo \
"nodejs" \
"https://deb.nodesource.com/gpgkey/nodesource.gpg.key" \
"https://deb.nodesource.com/node_22.x" \
"bookworm" \
"main"
```
### `prepare_repository_setup`
A high-level helper that performs three critical tasks before adding a new repo:
1. Cleans up old repo files matching the names provided.
2. Removes old GPG keyrings from all standard locations.
3. Ensures APT is in a working state (fixes locks, runs update).
```bash
# Clean up old mysql/mariadb artifacts before setup
prepare_repository_setup "mariadb" "mysql"
```
### `cleanup_tool_keyrings`
Force-removes GPG keys for specific tools from `/usr/share/keyrings/`, `/etc/apt/keyrings/`, and `/etc/apt/trusted.gpg.d/`.
```bash
cleanup_tool_keyrings "docker" "kubernetes"
```
---
## GitHub Release Helpers
> **Note**: `fetch_and_deploy_gh_release` is the **preferred method** for downloading GitHub releases. It handles version tracking automatically. Only use `get_latest_github_release` if you need the version number separately.
@@ -302,17 +361,17 @@ CLEAN_INSTALL=1 fetch_and_deploy_gh_release "appname" "owner/repo" "tarball" "la
```
**Parameters:**
| Parameter | Default | Description |
| Parameter | Default | Description |
| --------------- | ------------- | ----------------------------------------------------------------- |
| `name` | required | App name (for version tracking) |
| `repo` | required | GitHub repo (`owner/repo`) |
| `type` | `tarball` | Release type: `tarball`, `zipball`, `prebuild`, `binary` |
| `version` | `latest` | Version tag or `latest` |
| `dest` | `/opt/[name]` | Destination directory |
| `asset_pattern` | `""` | For `prebuild`: glob pattern to match asset (e.g. `app-*.tar.gz`) |
| `name` | required | App name (for version tracking) |
| `repo` | required | GitHub repo (`owner/repo`) |
| `type` | `tarball` | Release type: `tarball`, `zipball`, `prebuild`, `binary` |
| `version` | `latest` | Version tag or `latest` |
| `dest` | `/opt/[name]` | Destination directory |
| `asset_pattern` | `""` | For `prebuild`: glob pattern to match asset (e.g. `app-*.tar.gz`) |
**Environment Variables:**
| Variable | Description |
| Variable | Description |
| ----------------- | ------------------------------------------------------------ |
| `CLEAN_INSTALL=1` | Remove destination directory before extracting (for updates) |
@@ -339,26 +398,21 @@ RELEASE=$(get_latest_github_release "owner/repo")
echo "Latest version: $RELEASE"
```
# Examples
fetch_and_deploy_gh_release "bookstack" "BookStackApp/BookStack"
fetch_and_deploy_gh_release "appname" "owner/repo" "tarball" "latest" "/opt/myapp"
````
**Parameters:**
| Parameter | Default | Description |
| --------- | ------------- | -------------------------------------------- |
| `name` | required | App name (for version tracking) |
| `repo` | required | GitHub repo (`owner/repo`) |
| `type` | `tarball` | Release type: `tarball`, `zipball`, `binary` |
| `version` | `latest` | Version tag or `latest` |
| `dest` | `/opt/[name]` | Destination directory |
---
## Tools & Utilities
### `setup_meilisearch`
Install Meilisearch, a lightning-fast search engine.
```bash
setup_meilisearch
# Use in script
$STD php artisan scout:sync-index-settings
```
### `setup_yq`
Install yq YAML processor.
@@ -434,6 +488,15 @@ create_self_signed_cert
## Utility Functions
### `verify_tool_version`
Validate that the installed major version matches the expected version. Useful during upgrades or troubleshooting.
```bash
# Verify Node.js is version 22
verify_tool_version "nodejs" "22" "$(node -v | grep -oP '^v\K[0-9]+')"
```
### `get_lxc_ip`
Set the `$LOCAL_IP` variable with the container's IP address.
@@ -526,7 +589,7 @@ msg_ok "Installed Dependencies"
# Setup runtimes and databases FIRST
NODE_VERSION="22" setup_nodejs
PG_VERSION="17" setup_postgresql
PG_VERSION="16" setup_postgresql
PG_DB_NAME="myapp" PG_DB_USER="myapp" setup_postgresql_db
get_lxc_ip