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 ---