From b87fddbf6a43d3c7436a219133590a5e1c178ed6 Mon Sep 17 00:00:00 2001 From: CanbiZ <47820557+MickLesk@users.noreply.github.com> Date: Sun, 18 Jan 2026 18:56:21 +0100 Subject: [PATCH] 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/contribution/AI.md | 4 +- docs/contribution/CODE-AUDIT.md | 49 +++++-- docs/contribution/CONTRIBUTING.md | 2 +- docs/contribution/FORK_SETUP.md | 44 +++--- docs/contribution/GUIDE.md | 104 +++++--------- docs/contribution/HELPER_FUNCTIONS.md | 90 ++++++------ docs/contribution/README.md | 20 ++- docs/contribution/setup-fork.sh | 4 +- docs/contribution/templates_ct/AppName.md | 20 ++- .../templates_install/AppName-install.md | 2 +- docs/contribution/templates_json/AppName.md | 130 +++++++++++------- 11 files changed, 244 insertions(+), 225 deletions(-) diff --git a/docs/contribution/AI.md b/docs/contribution/AI.md index 0f4c7627d..2da59ed8e 100644 --- a/docs/contribution/AI.md +++ b/docs/contribution/AI.md @@ -200,7 +200,7 @@ CLEAN_INSTALL=1 fetch_and_deploy_gh_release "appname" "owner/repo" | Function | Variable(s) | Example | | -------------- | ----------------------------- | ---------------------------------------------------- | | `setup_nodejs` | `NODE_VERSION`, `NODE_MODULE` | `NODE_VERSION="22" setup_nodejs` | -| `setup_uv` | `UV_PYTHON` | `UV_PYTHON="3.12" setup_uv` | +| `setup_uv` | `PYTHON_VERSION` | `PYTHON_VERSION="3.12" setup_uv` | | `setup_go` | `GO_VERSION` | `GO_VERSION="1.22" setup_go` | | `setup_rust` | `RUST_VERSION`, `RUST_CRATES` | `RUST_CRATES="monolith" setup_rust` | | `setup_ruby` | `RUBY_VERSION` | `RUBY_VERSION="3.3" setup_ruby` | @@ -465,7 +465,7 @@ EOF msg_ok "Saved Credentials" # โœ… CORRECT - credentials are stored in .env or shown in final message only -# The .env file contains credentials, no need for separate file +# If you use setup_postgresql_db / setup_mariadb_db, a standard ~/[appname].creds is created automatically ``` ### 15. Wrong Footer Pattern diff --git a/docs/contribution/CODE-AUDIT.md b/docs/contribution/CODE-AUDIT.md index 17a1ff4a4..d1aedf275 100644 --- a/docs/contribution/CODE-AUDIT.md +++ b/docs/contribution/CODE-AUDIT.md @@ -1,14 +1,41 @@ -
- -
-

Exploring the Scripts and Steps Involved in an Application LXC Installation

+# ๐Ÿงช Code Audit: LXC Script Flow -1) [adguard.sh](https://github.com/community-scripts/ProxmoxVE/blob/main/ct/adguard.sh): This script collects system parameters. (Also holds the function to update the application.) -2) [build.func](https://github.com/community-scripts/ProxmoxVE/blob/main/misc/build.func): Adds user settings and integrates collected information. -3) [create_lxc.sh](https://github.com/community-scripts/ProxmoxVE/blob/main/misc/create_lxc.sh): Constructs the LXC container. -4) [adguard-install.sh](https://github.com/community-scripts/ProxmoxVE/blob/main/install/adguard-install.sh): Executes functions from [install.func](https://github.com/community-scripts/ProxmoxVE/blob/main/misc/install.func), and installs the application. -5) [adguard.sh](https://github.com/community-scripts/ProxmoxVE/blob/main/ct/adguard.sh) (again): To display the completion message. +This guide explains the current execution flow and what to verify during reviews. -The installation process uses reusable scripts: [build.func](https://github.com/community-scripts/ProxmoxVE/blob/main/misc/build.func), [create_lxc.sh](https://github.com/community-scripts/ProxmoxVE/blob/main/misc/create_lxc.sh), and [install.func](https://github.com/community-scripts/ProxmoxVE/blob/main/misc/install.func), which are not specific to any particular application. +## Execution Flow (CT + Install) -To gain a better understanding, focus on reviewing [adguard-install.sh](https://github.com/community-scripts/ProxmoxVE/blob/main/install/adguard-install.sh). This script contains the commands and configurations for installing and configuring AdGuard Home within the LXC container. +1. `ct/appname.sh` runs on the Proxmox host and sources `misc/build.func`. +2. `build.func` orchestrates prompts, container creation, and invokes the install script. +3. Inside the container, `misc/install.func` exposes helper functions via `$FUNCTIONS_FILE_PATH`. +4. `install/appname-install.sh` performs the application install. +5. The CT script prints the completion message. + +## Audit Checklist + +### CT Script (ct/) + +- Sources `misc/build.func` from `community-scripts/ProxmoxVE/main` (setup-fork.sh updates for forks). +- Uses `check_for_gh_release` + `fetch_and_deploy_gh_release` for updates. +- No Docker-based installs. + +### Install Script (install/) + +- Sources `$FUNCTIONS_FILE_PATH`. +- Uses `tools.func` helpers (setup\_\*). +- Ends with `motd_ssh`, `customize`, `cleanup_lxc`. + +### JSON Metadata + +- File in `frontend/public/json/.json` matches template schema. + +### Testing + +- Test via curl from your fork (CT script only). +- Wait 10-30 seconds after push. + +## References + +- `docs/contribution/templates_ct/AppName.sh` +- `docs/contribution/templates_install/AppName-install.sh` +- `docs/contribution/templates_json/AppName.json` +- `docs/contribution/GUIDE.md` diff --git a/docs/contribution/CONTRIBUTING.md b/docs/contribution/CONTRIBUTING.md index d2378d59b..5d7896fe2 100644 --- a/docs/contribution/CONTRIBUTING.md +++ b/docs/contribution/CONTRIBUTING.md @@ -84,7 +84,7 @@ git switch -c your-feature-branch ### 4. Run setup-fork.sh to auto-configure your fork ```bash -bash docs/contribution/setup-fork.sh +bash docs/contribution/setup-fork.sh --full ``` This script automatically: diff --git a/docs/contribution/FORK_SETUP.md b/docs/contribution/FORK_SETUP.md index 5993fbb67..0a25a30c7 100644 --- a/docs/contribution/FORK_SETUP.md +++ b/docs/contribution/FORK_SETUP.md @@ -10,7 +10,7 @@ git clone https://github.com/YOUR_USERNAME/ProxmoxVE.git cd ProxmoxVE # Run setup script (auto-detects your username from git) -bash setup-fork.sh +bash docs/contribution/setup-fork.sh --full ``` That's it! โœ… @@ -67,7 +67,7 @@ source <(curl -fsSL https://raw.githubusercontent.com/john/ProxmoxVE/main/misc/b ### Auto-Detect (Recommended) ```bash -bash setup-fork.sh +bash docs/contribution/setup-fork.sh --full ``` Automatically reads your GitHub username from `git remote origin url` @@ -75,7 +75,7 @@ Automatically reads your GitHub username from `git remote origin url` ### Specify Username ```bash -bash setup-fork.sh john +bash docs/contribution/setup-fork.sh --full john ``` Updates links to `github.com/john/ProxmoxVE` @@ -83,7 +83,7 @@ Updates links to `github.com/john/ProxmoxVE` ### Custom Repository Name ```bash -bash setup-fork.sh john my-fork +bash docs/contribution/setup-fork.sh --full john my-fork ``` Updates links to `github.com/john/my-fork` @@ -92,19 +92,12 @@ Updates links to `github.com/john/my-fork` ## What Gets Updated? -The script updates these documentation files: +The script updates hardcoded links in these areas when using `--full`: -- `docs/CONTRIBUTION_GUIDE.md` (4 links) -- `docs/README.md` (1 link) -- `docs/INDEX.md` (3 links) -- `docs/EXIT_CODES.md` (2 links) -- `docs/DEFAULTS_SYSTEM_GUIDE.md` (2 links) -- `docs/api/README.md` (1 link) -- `docs/APP-ct.md` (1 link) -- `docs/APP-install.md` (1 link) -- `docs/alpine-install.func.md` (2 links) -- `docs/install.func.md` (1 link) -- And code examples in documentation +- `ct/`, `install/`, `vm/` scripts +- `misc/` function libraries +- `docs/` (including `docs/contribution/`) +- Code examples in documentation --- @@ -132,7 +125,7 @@ The script updates these documentation files: 4. **Follow the guide** ```bash - cat docs/CONTRIBUTION_GUIDE.md + cat docs/contribution/GUIDE.md ``` --- @@ -179,7 +172,7 @@ git checkout -b feature/my-feature # Make sure you cloned the repo first git clone https://github.com/YOUR_USERNAME/ProxmoxVE.git cd ProxmoxVE -bash setup-fork.sh +bash docs/contribution/setup-fork.sh --full ``` ### "Could not auto-detect GitHub username" @@ -191,15 +184,15 @@ git remote -v # Fix it: git remote set-url origin https://github.com/YOUR_USERNAME/ProxmoxVE.git -bash setup-fork.sh +bash docs/contribution/setup-fork.sh --full ``` ### "Permission denied" ```bash # Make script executable -chmod +x setup-fork.sh -bash setup-fork.sh +chmod +x docs/contribution/setup-fork.sh +bash docs/contribution/setup-fork.sh --full ``` ### Reverted Changes by Accident? @@ -208,14 +201,15 @@ bash setup-fork.sh # Backups are created automatically git checkout docs/*.backup # Or just re-run setup-fork.sh +bash docs/contribution/setup-fork.sh --full ``` --- ## Next Steps -1. โœ… Run `bash setup-fork.sh` -2. ๐Ÿ“– Read [docs/CONTRIBUTION_GUIDE.md](docs/CONTRIBUTION_GUIDE.md) +1. โœ… Run `bash docs/contribution/setup-fork.sh --full` +2. ๐Ÿ“– Read [docs/contribution/GUIDE.md](GUIDE.md) 3. ๐Ÿด Choose your contribution path: - **Containers** โ†’ [docs/ct/README.md](docs/ct/README.md) - **Installation** โ†’ [docs/install/README.md](docs/install/README.md) @@ -228,10 +222,10 @@ git checkout docs/*.backup ## Questions? - **Fork Setup Issues?** โ†’ See [Troubleshooting](#troubleshooting) above -- **How to Contribute?** โ†’ [docs/CONTRIBUTION_GUIDE.md](docs/CONTRIBUTION_GUIDE.md) +- **How to Contribute?** โ†’ [docs/contribution/GUIDE.md](GUIDE.md) - **Git Workflows?** โ†’ `cat .git-setup-info` - **Project Structure?** โ†’ [docs/README.md](docs/README.md) --- -**Happy Contributing! ๐Ÿš€** +## Happy Contributing! ๐Ÿš€ diff --git a/docs/contribution/GUIDE.md b/docs/contribution/GUIDE.md index 3ca4f43c7..e2d580976 100644 --- a/docs/contribution/GUIDE.md +++ b/docs/contribution/GUIDE.md @@ -38,8 +38,8 @@ git clone https://github.com/YOUR_USERNAME/ProxmoxVE.git cd ProxmoxVE # 3. Run fork setup script (automatically configures everything) -bash setup-fork.sh -# This auto-detects your username and updates all documentation links +bash docs/contribution/setup-fork.sh --full +# --full updates ct/, install/, vm/, docs/, misc/ links for fork testing # 4. Read the git workflow tips cat .git-setup-info @@ -113,9 +113,9 @@ ProxmoxVE/ โ”‚ โ””โ”€โ”€ alpine-tools.func # Alpine tools โ”‚ โ”œโ”€โ”€ docs/ # ๐Ÿ“š Documentation -โ”‚ โ”œโ”€โ”€ UPDATED_APP-ct.md # Container script guide -โ”‚ โ”œโ”€โ”€ UPDATED_APP-install.md # Install script guide -โ”‚ โ””โ”€โ”€ CONTRIBUTING.md # (This file!) +โ”‚ โ”œโ”€โ”€ ct/DETAILED_GUIDE.md # Container script guide +โ”‚ โ”œโ”€โ”€ install/DETAILED_GUIDE.md # Install script guide +โ”‚ โ””โ”€โ”€ contribution/README.md # Contribution overview โ”‚ โ”œโ”€โ”€ tools/ # ๐Ÿ”ง Proxmox management tools โ”‚ โ””โ”€โ”€ pve/ @@ -201,27 +201,18 @@ git rebase upstream/main git push origin feat/add-myapp ``` -#### Option B: Local Testing on Proxmox Host +#### Option B: Testing on a Proxmox Host (still via curl) -````bash +```bash # 1. SSH into Proxmox host ssh root@192.168.1.100 -# 2. Download your script -curl -O https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/feat/myapp/ct/myapp.sh +# 2. Test via curl from your fork (CT script only) +bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/ct/myapp.sh)" +# โฑ๏ธ Wait 10-30 seconds after pushing - GitHub takes time to update +``` -# 3. Make it executable -chmod +x myapp.sh - -# 4. Update URLs to your fork -# Edit: curl -s https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/feat/myapp/... - -# 5. Run and test -```bash -bash myapp.sh - -# 6. If container created successfully, script is working! -```` +> **Note:** Do not edit URLs manually or run install scripts directly. The CT script calls the install script inside the container. #### Option C: Using Curl (Recommended for Real Testing) @@ -232,11 +223,11 @@ bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/ # This tests the actual GitHub URLs, not local files ``` -#### Option D: Docker Testing (Without Proxmox) +#### Option D: Static Checks (Without Proxmox) ```bash -# You can test script syntax/functionality locally (limited) -# Note: Won't fully test (no Proxmox, no actual container) +# You can validate syntax and linting locally (limited) +# Note: This does NOT replace real Proxmox testing # Run ShellCheck shellcheck ct/myapp.sh @@ -260,12 +251,9 @@ cp ct/example.sh ct/myapp.sh cp install/example-install.sh install/myapp-install.sh ``` -**For Database Apps** (PostgreSQL, MongoDB): +**For Database Apps** (PostgreSQL, MariaDB, MongoDB): -```bash -cp ct/docker.sh ct/myapp.sh # Use Docker container -# OR manual setup for more control -``` +Use the standard templates and the database helpers from `tools.func` (no Docker). **For Alpine Linux Apps** (lightweight): @@ -280,7 +268,7 @@ cp ct/docker.sh ct/myapp.sh # Use Docker container ```bash #!/usr/bin/env bash -source <(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/feat/myapp/misc/build.func) +source <(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/misc/build.func) # Update these: APP="MyAwesomeApp" # Display name @@ -307,17 +295,19 @@ function update_script() { exit fi - # Get latest version - RELEASE=$(curl -fsSL https://api.github.com/repos/user/repo/releases/latest | \ - grep "tag_name" | awk '{print substr($2, 2, length($2)-3)}') + if check_for_gh_release "myapp" "owner/repo"; then + msg_info "Stopping Service" + systemctl stop myapp + msg_ok "Stopped Service" - if [[ ! -f /opt/${APP}_version.txt ]] || [[ "${RELEASE}" != "$(cat /opt/${APP}_version.txt)" ]]; then - msg_info "Updating ${APP} to v${RELEASE}" - # ... update logic ... - echo "${RELEASE}" > /opt/${APP}_version.txt - msg_ok "Updated ${APP}" - else - msg_ok "No update required. ${APP} is already at v${RELEASE}." + CLEAN_INSTALL=1 fetch_and_deploy_gh_release "myapp" "owner/repo" "tarball" "latest" "/opt/myapp" + + # ... update logic (migrations, rebuilds, etc.) ... + + msg_info "Starting Service" + systemctl start myapp + msg_ok "Started Service" + msg_ok "Updated successfully!" fi exit } @@ -362,24 +352,12 @@ update_os msg_info "Installing Dependencies" $STD apt-get install -y \ - curl \ - wget \ - git \ build-essential msg_ok "Installed Dependencies" -msg_info "Setting up Node.js" NODE_VERSION="22" setup_nodejs -msg_ok "Node.js installed" -msg_info "Downloading Application" -cd /opt -wget -q "https://github.com/user/repo/releases/download/v1.0.0/myapp.tar.gz" -tar -xzf myapp.tar.gz -rm -f myapp.tar.gz -msg_ok "Application installed" - -echo "1.0.0" > /opt/${APP}_version.txt +fetch_and_deploy_gh_release "myapp" "owner/repo" "tarball" "latest" "/opt/myapp" motd_ssh customize @@ -674,27 +652,19 @@ shellcheck install/myapp-install.sh # 1. SSH into Proxmox host ssh root@YOUR_PROXMOX_IP -# 2. Download your script -curl -O https://raw.githubusercontent.com/YOUR_USER/ProxmoxVE/feat/myapp/ct/myapp.sh +# 2. Test via curl from your fork (CT script only) +bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/ct/myapp.sh)" +# โฑ๏ธ Wait 10-30 seconds after pushing - GitHub takes time to update -# 3. Make executable -chmod +x myapp.sh - -# 4. UPDATE URLS IN SCRIPT to point to your fork -sed -i 's|community-scripts|YOUR_USER|g' myapp.sh - -# 5. Run script -bash myapp.sh - -# 6. Test interaction: +# 3. Test interaction: # - Select installation mode # - Confirm settings # - Monitor installation -# 7. Verify container created +# 4. Verify container created pct list | grep myapp -# 8. Log into container and verify app +# 5. Log into container and verify app pct exec 100 bash ``` diff --git a/docs/contribution/HELPER_FUNCTIONS.md b/docs/contribution/HELPER_FUNCTIONS.md index b5cc6ead3..d1a7622d5 100644 --- a/docs/contribution/HELPER_FUNCTIONS.md +++ b/docs/contribution/HELPER_FUNCTIONS.md @@ -30,61 +30,63 @@ > โš ๏ธ **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) | ### 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 +97,7 @@ Install Node.js from NodeSource repository. ```bash -# Default (Node.js 22) +# Default (Node.js 24) setup_nodejs # Specific version @@ -135,8 +137,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 +166,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 +174,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 +245,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` @@ -302,17 +308,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) | @@ -526,7 +532,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 import_local_ip diff --git a/docs/contribution/README.md b/docs/contribution/README.md index 88d8aea76..be1231855 100644 --- a/docs/contribution/README.md +++ b/docs/contribution/README.md @@ -30,7 +30,7 @@ git clone https://github.com/YOUR_USERNAME/ProxmoxVE.git cd ProxmoxVE # 3. Auto-configure your fork (IMPORTANT - updates all links!) -bash docs/contribution/setup-fork.sh +bash docs/contribution/setup-fork.sh --full # 4. Create a feature branch git checkout -b feature/my-awesome-app @@ -54,9 +54,8 @@ bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/ cp docs/contribution/templates_json/AppName.json frontend/public/json/myapp.json # Edit metadata: name, slug, categories, description, resources, etc. -# 9. Test the install script (if you created one) -bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/install/myapp-install.sh)" -# โฑ๏ธ GitHub may take 10-30 seconds to update files - be patient! +# 9. No direct install-script test +# Install scripts are executed by the CT script inside the container # 10. Commit ONLY your new files (see Cherry-Pick section below!) git add ct/myapp.sh install/myapp-install.sh frontend/public/json/myapp.json @@ -78,8 +77,7 @@ Once your script is merged to the main repository, users download and run it fro # โœ… Users run from GitHub (normal usage after PR merged) bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/myapp.sh)" -# For installation on existing Proxmox hosts -bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/install/myapp-install.sh)" +# Install scripts are called by the CT script and are not run directly by users ``` ### Development vs. Production Execution @@ -119,14 +117,14 @@ bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/Proxmo When you clone your fork, run the setup script to automatically configure everything: ```bash -bash docs/contribution/setup-fork.sh +bash docs/contribution/setup-fork.sh --full ``` **What it does:** - Auto-detects your GitHub username from git config - Auto-detects your fork repository name -- Updates **ALL** hardcoded links to point to your fork instead of the main repo +- Updates **ALL** hardcoded links to point to your fork instead of the main repo (`--full`) - Creates `.git-setup-info` with your configuration - Allows you to develop and test independently in your fork @@ -182,7 +180,7 @@ All scripts and configurations must follow our coding standards to ensure consis - **[HELPER_FUNCTIONS.md](HELPER_FUNCTIONS.md)** - Reference for all tools.func helper functions - **Container Scripts** - `/ct/` templates and guidelines - **Install Scripts** - `/install/` templates and guidelines -- **JSON Configurations** - `/json/` structure and format +- **JSON Configurations** - `frontend/public/json/` structure and format ### Quick Checklist @@ -581,7 +579,7 @@ Two ways: **Option 1: Run setup script again** ```bash -bash docs/contribution/setup-fork.sh +bash docs/contribution/setup-fork.sh --full ``` **Option 2: Manual sync** @@ -633,7 +631,7 @@ See "Using AI Assistants" section above for: ## ๐Ÿš€ Ready to Contribute? 1. **Fork** the repository -2. **Clone** your fork and **setup** with `bash docs/contribution/setup-fork.sh` +2. **Clone** your fork and **setup** with `bash docs/contribution/setup-fork.sh --full` 3. **Choose** your contribution type (container, installation, tools, etc.) 4. **Read** the appropriate detailed guide 5. **Create** your feature branch diff --git a/docs/contribution/setup-fork.sh b/docs/contribution/setup-fork.sh index 42acc23d6..5ac54b90c 100644 --- a/docs/contribution/setup-fork.sh +++ b/docs/contribution/setup-fork.sh @@ -220,7 +220,7 @@ git merge upstream/main --- -For more help, see: docs/CONTRIBUTION_GUIDE.md +For more help, see: docs/contribution/README.md EOF print_success "Created .git-setup-info file" @@ -328,7 +328,7 @@ echo -e "${BLUE}Next Steps:${NC}" echo " 1. Review the changes: git diff" echo " 2. Check .git-setup-info for recommended git workflow" echo " 3. Start developing: git checkout -b feature/my-app" -echo " 4. Read: docs/CONTRIBUTION_GUIDE.md" +echo " 4. Read: docs/contribution/README.md" echo "" print_success "Happy contributing! ๐Ÿš€" diff --git a/docs/contribution/templates_ct/AppName.md b/docs/contribution/templates_ct/AppName.md index b6575c7cf..1739b7976 100644 --- a/docs/contribution/templates_ct/AppName.md +++ b/docs/contribution/templates_ct/AppName.md @@ -102,8 +102,8 @@ function update_script() { check_container_resources # Use tools.func helpers: - check_for_gh_release "myapp" "YourUsername/ProxmoxVE" - fetch_and_deploy_gh_release "myapp" "app/owner" "appname.tar.gz" "latest" "/opt/myapp" + check_for_gh_release "myapp" "owner/repo" + fetch_and_deploy_gh_release "myapp" "owner/repo" "tarball" "latest" "/opt/myapp" } ``` @@ -111,20 +111,20 @@ function update_script() { ## Key Patterns -### Check for Updates (ProxmoxVE Fork) +### Check for Updates (App Repository) -Use `check_for_gh_release` with **YOUR fork**: +Use `check_for_gh_release` with the **app repo**: ```bash -check_for_gh_release "myapp" "YourUsername/ProxmoxVE" +check_for_gh_release "myapp" "owner/repo" ``` ### Deploy External App -Use `fetch_and_deploy_gh_release` with **target app repo**: +Use `fetch_and_deploy_gh_release` with the **app repo**: ```bash -fetch_and_deploy_gh_release "myapp" "myapp/repo" "appname.tar.gz" "latest" "/opt/myapp" +fetch_and_deploy_gh_release "myapp" "owner/repo" ``` ### Avoid Manual Version Checking @@ -138,7 +138,7 @@ RELEASE=$(curl -fsSL https://api.github.com/repos/myapp/myapp/releases/latest | โœ… NEW (use tools.func): ```bash -fetch_and_deploy_gh_release "myapp" "myapp/repo" "appname.tar.gz" "latest" "/opt/myapp" +fetch_and_deploy_gh_release "myapp" "owner/repo" ``` --- @@ -172,10 +172,6 @@ Recent reference scripts with good update functions: - **[AI.md](../AI.md)** - AI-generated script guidelines - **[FORK_SETUP.md](../FORK_SETUP.md)** - Why setup-fork.sh is important - **[Slack Community](https://discord.gg/your-link)** - Ask questions - msg_ok "No update required. ${APP} is already at v${RELEASE}." - fi - exit - } ```` diff --git a/docs/contribution/templates_install/AppName-install.md b/docs/contribution/templates_install/AppName-install.md index e64c1806b..9d8388734 100644 --- a/docs/contribution/templates_install/AppName-install.md +++ b/docs/contribution/templates_install/AppName-install.md @@ -5,7 +5,7 @@ > > Current templates use: > -> - `tools.func` helpers (setup_nodejs, setup_python, setup_postgresql_db, etc.) +> - `tools.func` helpers (setup_nodejs, setup_uv, setup_postgresql_db, etc.) > - Automatic dependency installation via build.func > - Standardized environment variable patterns diff --git a/docs/contribution/templates_json/AppName.md b/docs/contribution/templates_json/AppName.md index d77823c38..1eb4ed61f 100644 --- a/docs/contribution/templates_json/AppName.md +++ b/docs/contribution/templates_json/AppName.md @@ -21,30 +21,40 @@ The metadata file (`frontend/public/json/myapp.json`) tells the web interface ho { "name": "MyApp", "slug": "myapp", - "categories": ["utilities", "monitoring"], - "date_created": "2025-01-15", + "categories": [1], + "date_created": "2026-01-18", "type": "ct", - "interface_port": "3000", - "logo": "https://example.com/logo.png", - "config_path": "/etc/myapp/config.json", + "updateable": true, + "privileged": false, + "interface_port": 3000, + "documentation": "https://docs.example.com/", + "website": "https://example.com/", + "logo": "https://cdn.jsdelivr.net/gh/selfhst/icons@main/webp/myapp.webp", + "config_path": "/opt/myapp/.env", "description": "Brief description of what MyApp does", - "install_methods": { - "1": { - "type": "ct", + "install_methods": [ + { + "type": "default", + "script": "ct/myapp.sh", "resources": { - "cpu": "2", - "ram": "2048", - "disk": "10" - }, - "pre_install_msg": "Optional message shown before installation" + "cpu": 2, + "ram": 2048, + "hdd": 8, + "os": "Debian", + "version": "13" + } } - }, + ], "default_credentials": { - "username": "admin", - "password": "Generated during install" + "username": null, + "password": null }, - "notes": "Optional setup notes", - "notes_type": "markdown" + "notes": [ + { + "text": "Change the default password after first login!", + "type": "warning" + } + ] } ``` @@ -52,21 +62,20 @@ The metadata file (`frontend/public/json/myapp.json`) tells the web interface ho ## Field Reference -| Field | Required | Example | Notes | -| --------------------- | -------- | ------------------------ | ---------------------------------------------- | -| `name` | Yes | "MyApp" | Display name | -| `slug` | Yes | "myapp" | URL-friendly identifier (lowercase, no spaces) | -| `categories` | Yes | ["utilities"] | One or more from available list | -| `date_created` | Yes | "2025-01-15" | Format: YYYY-MM-DD | -| `type` | Yes | "ct" | Container type: "ct" or "vm" | -| `interface_port` | Yes | "3000" | Default web interface port | -| `logo` | No | "https://..." | Logo URL (64px x 64px PNG) | -| `config_path` | Yes | "/etc/myapp/config.json" | Main config file location | -| `description` | Yes | "App description" | Brief description (100 chars) | -| `install_methods` | Yes | See below | Installation resources | -| `default_credentials` | No | See below | Optional default login | -| `notes` | No | "Setup info" | Additional notes | -| `notes_type` | No | "markdown" | Format of notes field | +| Field | Required | Example | Notes | +| --------------------- | -------- | ----------------- | ---------------------------------------------- | +| `name` | Yes | "MyApp" | Display name | +| `slug` | Yes | "myapp" | URL-friendly identifier (lowercase, no spaces) | +| `categories` | Yes | [1] | One or more category IDs | +| `date_created` | Yes | "2026-01-18" | Format: YYYY-MM-DD | +| `type` | Yes | "ct" | Container type: "ct" or "vm" | +| `interface_port` | Yes | 3000 | Default web interface port | +| `logo` | No | "https://..." | Logo URL (64px x 64px PNG) | +| `config_path` | Yes | "/opt/myapp/.env" | Main config file location | +| `description` | Yes | "App description" | Brief description (100 chars) | +| `install_methods` | Yes | See below | Installation resources (array) | +| `default_credentials` | No | See below | Optional default login | +| `notes` | No | See below | Additional notes (array) | --- @@ -75,17 +84,19 @@ The metadata file (`frontend/public/json/myapp.json`) tells the web interface ho Each installation method specifies resource requirements: ```json -"install_methods": { - "1": { - "type": "ct", +"install_methods": [ + { + "type": "default", + "script": "ct/myapp.sh", "resources": { - "cpu": "2", - "ram": "2048", - "disk": "10" - }, - "pre_install_msg": "Optional message" + "cpu": 2, + "ram": 2048, + "hdd": 8, + "os": "Debian", + "version": "13" + } } -} +] ``` **Resource Defaults:** @@ -98,15 +109,32 @@ Each installation method specifies resource requirements: ## Common Categories -- `utilities` - Tools and utilities -- `monitoring` - Monitoring/logging -- `media` - Media servers -- `databases` - Database systems -- `communication` - Chat/messaging -- `smart-home` - Home automation -- `development` - Dev tools -- `security` - Security tools -- `storage` - File storage +- `0` Miscellaneous +- `1` Proxmox & Virtualization +- `2` Operating Systems +- `3` Containers & Docker +- `4` Network & Firewall +- `5` Adblock & DNS +- `6` Authentication & Security +- `7` Backup & Recovery +- `8` Databases +- `9` Monitoring & Analytics +- `10` Dashboards & Frontends +- `11` Files & Downloads +- `12` Documents & Notes +- `13` Media & Streaming +- `14` \*Arr Suite +- `15` NVR & Cameras +- `16` IoT & Smart Home +- `17` ZigBee, Z-Wave & Matter +- `18` MQTT & Messaging +- `19` Automation & Scheduling +- `20` AI / Coding & Dev-Tools +- `21` Webservers & Proxies +- `22` Bots & ChatOps +- `23` Finance & Budgeting +- `24` Gaming & Leisure +- `25` Business & ERP ---