Proxmox/ProxmoxVE
1
0
Fork 1
mirror of https://github.com/community-scripts/ProxmoxVE.git synced 2026-07-16 10:55:07 +02:00
Code Issues Packages Projects Releases Wiki Activity

Docs: expand developer/debugging and tools references

Browse Source 
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 15:16:35 +01:00
parent 30bc127011
commit 2c18646d82
8 changed files with 410 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/contribution/CONTRIBUTING.md
+24
View File
@@ -147,6 +147,30 @@ Verify the PR shows ONLY these 3 files:
---
# 🛠️ Developer Mode & Debugging
When building or testing scripts, you can use the `dev_mode` variable to enable powerful debugging features. These flags can be combined (comma-separated).
**Usage**:
```bash
# Example: Run with trace and keep the container even if it fails
dev_mode="trace,keep" bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/myapp.sh)"
```
### Available Flags:
| Flag | Description |
| :--- | :--- |
| `trace` | Enables `set -x` for maximum verbosity during execution. |
| `keep` | Prevents the container from being deleted if the build fails. |
| `pause` | Pauses execution at key points (e.g., before customization). |
| `breakpoint` | Allows hardcoded `breakpoint` calls in scripts to drop to a shell. |
| `logs` | Saves detailed build logs to `/var/log/community-scripts/`. |
| `dryrun` | Bypasses actual container creation (limited support). |
| `motd` | Forces an update of the Message of the Day (MOTD). |
---
## 📚 Pages
- [CT Template: AppName.sh](https://github.com/community-scripts/ProxmoxVE/blob/main/docs/contribution/templates_ct/AppName.sh)
docs/contribution/GUIDE.md
+36 -18
View File
@@ -433,26 +433,44 @@ $STD apt-get install -y newdependency
# 4. Test thoroughly before committing
```
### Step 3: Update Update Function (if applicable)
### Step 3: The Standard Update Pattern
The `update_script()` function in `ct/appname.sh` should follow a robust pattern:
1. **Check for updates**: Use `check_for_gh_release` to skip logic if no new version exists.
2. **Stop services**: Stop all relevant services (`systemctl stop appname`).
3. **Backup existing installation**: Move the old folder (e.g., `mv /opt/app /opt/app_bak`).
4. **Deploy new version**: Use `CLEAN_INSTALL=1 fetch_and_deploy_gh_release`.
5. **Restore configuration**: Copy `.env` or config files back from the backup.
6. **Rebuild/Migrate**: Run `npm install`, `composer install`, or DB migrations.
7. **Start services**: Restart services and cleanup the backup.
**Example from `ct/bookstack.sh`**:
```bash
# Edit: ct/existingapp.sh → update_script()
# 1. Update GitHub API URL if repo changed
RELEASE=$(curl -fsSL https://api.github.com/repos/user/repo/releases/latest | ...)
# 2. Update backup/restore logic (if structure changed)
# 3. Update cleanup paths
# 4. Test update on existing installation
```
### Step 4: Document Your Changes
```bash
# Add comment at top of script
# Co-Author: YourUsername
# Updated: YYYY-MM-DD - Description of changes
function update_script() {
if check_for_gh_release "bookstack" "BookStackApp/BookStack"; then
msg_info "Stopping Services"
systemctl stop apache2
msg_info "Backing up data"
mv /opt/bookstack /opt/bookstack-backup
fetch_and_deploy_gh_release "bookstack" "BookStackApp/BookStack" "tarball"
msg_info "Restoring backup"
cp /opt/bookstack-backup/.env /opt/bookstack/.env
# ... restore uploads ...
msg_info "Configuring"
cd /opt/bookstack
$STD composer install --no-dev
$STD php artisan migrate --force
systemctl start apache2
rm -rf /opt/bookstack-backup
msg_ok "Updated successfully!"
fi
}
```
---
docs/contribution/HELPER_FUNCTIONS.md
+73 -16
View File
@@ -60,6 +60,22 @@ Install scripts are **not** run directly by users; they are invoked by the CT sc
| 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
@@ -285,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.
@@ -345,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.
@@ -440,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.
docs/contribution/templates_install/AppName-install.sh
+4 -2
View File
@@ -30,14 +30,16 @@ msg_ok "Installed Dependencies"
# Examples (uncomment as needed):
#
# NODE_VERSION="22" setup_nodejs
# NODE_VERSION="22" NODE_MODULE="pnpm" setup_nodejs # Installs pnpm
# PYTHON_VERSION="3.13" setup_uv
# JAVA_VERSION="17" setup_java
# JAVA_VERSION="21" setup_java
# GO_VERSION="1.22" setup_go
# PHP_VERSION="8.4" PHP_FPM="YES" setup_php
# setup_postgresql # Server only
# setup_mariadb # Server only
# setup_meilisearch # Search engine
#
# Then set up DB and user:
# Then set up DB and user (sets $[DB]_DB_PASS):
# PG_DB_NAME="myapp" PG_DB_USER="myapp" setup_postgresql_db
# MARIADB_DB_NAME="myapp" MARIADB_DB_USER="myapp" setup_mariadb_db