diff --git a/docs/contribution/AI.md b/docs/contribution/AI.md index 59d231d21..d0f663e9e 100644 --- a/docs/contribution/AI.md +++ b/docs/contribution/AI.md @@ -629,6 +629,7 @@ cleanup_lxc Look at these recent well-implemented applications as reference: ### Container Scripts (Latest 10) + - [ct/thingsboard.sh](../ct/thingsboard.sh) - IoT platform with proper update_script - [ct/unifi-os-server.sh](../ct/unifi-os-server.sh) - Complex setup with podman - [ct/trip.sh](../ct/trip.sh) - Simple Ruby app @@ -638,14 +639,16 @@ Look at these recent well-implemented applications as reference: - [ct/flatnotes.sh](../ct/flatnotes.sh) - Python notes app - [ct/investbrain.sh](../ct/investbrain.sh) - Finance app - [ct/gwn-manager.sh](../ct/gwn-manager.sh) - Network management -- [ct/sportarr.sh](../ct/sportarr.sh) - Specialized *Arr variant +- [ct/sportarr.sh](../ct/sportarr.sh) - Specialized \*Arr variant ### Install Scripts (Latest) + - [install/unifi-os-server-install.sh](../install/unifi-os-server-install.sh) - Complex setup with API integration - [install/trip-install.sh](../install/trip-install.sh) - Rails application setup - [install/mail-archiver-install.sh](../install/mail-archiver-install.sh) - Email-related service **Key things to notice:** + - Proper error handling with `catch_errors` - Use of `check_for_gh_release` and `fetch_and_deploy_gh_release` - Correct backup/restore patterns in `update_script` diff --git a/docs/contribution/FORK_SETUP.md b/docs/contribution/FORK_SETUP.md index 3fa3ab71c..6975155af 100644 --- a/docs/contribution/FORK_SETUP.md +++ b/docs/contribution/FORK_SETUP.md @@ -22,9 +22,25 @@ That's it! ✅ The `setup-fork.sh` script automatically: 1. **Detects** your GitHub username from git config -2. **Updates** 22 hardcoded links in documentation to point to your fork -3. **Creates** `.git-setup-info` with recommended git workflows -4. **Backs up** all modified files (*.backup) +2. **Updates ALL hardcoded links** to point to your fork: + - Documentation links pointing to `community-scripts/ProxmoxVE` + - **Curl download URLs** in scripts (e.g., `curl ... github.com/community-scripts/ProxmoxVE/main/...`) +3. **Creates** `.git-setup-info` with your configuration details +4. **Backs up** all modified files (*.backup for safety) + +### Why Updating Curl Links Matters + +When you test scripts locally during development, the `curl` commands in your scripts need to pull from YOUR fork, not the upstream repository: + +```bash +# During local testing, after setup-fork.sh runs: +bash ct/myapp.sh +# This will curl from: github.com/YOUR_USERNAME/ProxmoxVE/main +# NOT from: github.com/community-scripts/ProxmoxVE/main + +# Once merged to upstream and published, users run: +bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/myapp.sh)" +``` --- diff --git a/docs/contribution/README.md b/docs/contribution/README.md index fa65ca12d..c838c4cd7 100644 --- a/docs/contribution/README.md +++ b/docs/contribution/README.md @@ -17,7 +17,9 @@ Complete guide to contributing to the ProxmoxVE project - from your first fork t ## 🚀 Quick Start -### 60 Seconds to Contributing +### 60 Seconds to Contributing (Development) + +When developing and testing **in your fork**: ```bash # 1. Fork on GitHub @@ -27,7 +29,7 @@ Complete guide to contributing to the ProxmoxVE project - from your first fork t git clone https://github.com/YOUR_USERNAME/ProxmoxVE.git cd ProxmoxVE -# 3. Auto-configure your fork +# 3. Auto-configure your fork (IMPORTANT - updates all links!) bash docs/contribution/setup-fork.sh # 4. Create a feature branch @@ -39,19 +41,54 @@ cat docs/ct/DETAILED_GUIDE.md # For container scripts cat docs/install/DETAILED_GUIDE.md # For install scripts # 6. Create your contribution -cp ct/example.sh ct/myapp.sh -cp install/example-install.sh install/myapp-install.sh +cp docs/contribution/templates_ct/AppName.sh ct/myapp.sh +cp docs/contribution/templates_install/AppName-install.sh install/myapp-install.sh # ... edit files ... -# 7. Test and commit +# 7. Test locally (in your fork before PR) bash ct/myapp.sh -git add ct/myapp.sh install/myapp-install.sh -git commit -m "feat: add MyApp" +# ⚠️ Important: Always use `bash ct/myapp.sh`, NOT `./ct/myapp.sh` + +# 8. Create your JSON metadata file +cp docs/contribution/templates_json/AppName.json frontend/public/json/myapp.json +# Edit metadata: name, slug, categories, description, resources, etc. + +# 9. Test locally (in your fork before PR) +bash ct/myapp.sh +# ⚠️ Important: Always use `bash ct/myapp.sh`, NOT `./ct/myapp.sh` + +# 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 +git commit -m "feat: add MyApp container and install scripts" git push origin feature/my-awesome-app -# 8. Create Pull Request on GitHub +# 11. Create Pull Request on GitHub ``` +⚠️ **IMPORTANT: After setup-fork.sh, many files are modified!** + +See the **Cherry-Pick: Submitting Only Your Changes** section below to learn how to push ONLY your 3-4 files instead of 600+ modified files! + +### How Users Run Scripts (After Merged) + +Once your script is merged to the main repository, users run it like this: + +```bash +# ✅ Users run from GitHub (normal usage) +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)" + +# ❌ NOT from local files (that's only for development) +bash ct/myapp.sh # Only works during development in your fork +``` + +**Why the difference?** +- **Development**: You test locally in your fork with `bash ct/myapp.sh` +- **Production**: Users always download from GitHub with `curl | bash` +- **setup-fork.sh**: Updates all your fork's links so curl pulls from YOUR fork during testing + --- ## 🍴 Setting Up Your Fork @@ -64,11 +101,30 @@ When you clone your fork, run the setup script to automatically configure everyt bash docs/contribution/setup-fork.sh ``` -This will: +**What it does:** -- Auto-detect your GitHub username -- Update all documentation links to point to your fork -- Create `.git-setup-info` with recommended git workflows +- 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 +- Creates `.git-setup-info` with your configuration +- Allows you to develop and test independently in your fork + +**Why this matters:** + +Without running this script, all links in your fork will still point to the upstream repository (community-scripts). This is a problem when testing because: + +- Installation links will pull from upstream, not your fork +- Updates will target the wrong repository +- Your contributions won't be properly tested + +**After running setup-fork.sh:** + +Your fork is fully configured and ready to develop. You can: + +- Test changes locally with `bash ct/myapp.sh` +- All links will reference your fork for development +- Commit and push with confidence +- Create a PR to merge into upstream **See**: [FORK_SETUP.md](FORK_SETUP.md) for detailed instructions @@ -81,11 +137,12 @@ If the script doesn't work, manually configure: git config user.name "Your Name" git config user.email "your.email@example.com" -# Add upstream remote for syncing +# Add upstream remote for syncing with main repo git remote add upstream https://github.com/community-scripts/ProxmoxVE.git # Verify remotes git remote -v +# Should show: origin (your fork) and upstream (main repo) ``` --- @@ -133,7 +190,168 @@ Key points: --- -## 📚 Guides & Resources +## 🍒 Cherry-Pick: Submitting Only Your Changes + +**Problem**: `setup-fork.sh` modifies 600+ files to update links. You don't want to submit all of those changes - only your new 3-4 files! + +**Solution**: Use git cherry-pick to select only YOUR files. + +### Step-by-Step Cherry-Pick Guide + +#### 1. Check what changed + +```bash +# See all modified files +git status + +# Verify your files are there +git status | grep -E "ct/myapp|install/myapp|json/myapp" +``` + +#### 2. Create a clean feature branch for submission + +```bash +# Go back to upstream main (clean slate) +git fetch upstream +git checkout -b submit/myapp upstream/main + +# Don't use your modified main branch! +``` + +#### 3. Cherry-pick ONLY your files + +Cherry-picking extracts specific changes from commits: + +```bash +# Option A: Cherry-pick commits that added your files +# (if you committed your files separately) +git cherry-pick + +# Option B: Manually copy and commit only your files +# From your work branch, get the file contents +git show feature/my-awesome-app:ct/myapp.sh > /tmp/myapp.sh +git show feature/my-awesome-app:install/myapp-install.sh > /tmp/myapp-install.sh +git show feature/my-awesome-app:frontend/public/json/myapp.json > /tmp/myapp.json + +# Add them to the clean branch +cp /tmp/myapp.sh ct/myapp.sh +cp /tmp/myapp-install.sh install/myapp-install.sh +cp /tmp/myapp.json frontend/public/json/myapp.json + +# Commit +git add ct/myapp.sh install/myapp-install.sh frontend/public/json/myapp.json +git commit -m "feat: add MyApp" +``` + +#### 4. Verify only your files are in the PR + +```bash +# Check git diff against upstream +git diff upstream/main --name-only +# Should show ONLY: +# ct/myapp.sh +# install/myapp-install.sh +# frontend/public/json/myapp.json +``` + +#### 5. Push and create PR + +```bash +# Push your clean submission branch +git push origin submit/myapp + +# Create PR on GitHub from: submit/myapp → main +``` + +### Why This Matters + +- ✅ Clean PR with only your changes +- ✅ Easier for maintainers to review +- ✅ Faster merge without conflicts +- ❌ Without cherry-pick: PR has 600+ file changes (won't merge!) + +### If You Made a Mistake + +```bash +# Delete the messy branch +git branch -D submit/myapp + +# Go back to clean branch +git checkout -b submit/myapp upstream/main + +# Try cherry-picking again +``` + +--- + +If you're using **Visual Studio Code** with an AI assistant, you can leverage our detailed guidelines to generate high-quality contributions automatically. + +### How to Use AI Assistance + +1. **Open the AI Guidelines** + + ``` + docs/contribution/AI.md + ``` + + This file contains all requirements, patterns, and examples for writing proper scripts. + +2. **Prepare Your Information** + + Before asking the AI to generate code, gather: + - **Repository URL**: e.g., `https://github.com/owner/myapp` + - **Dockerfile/Script**: Paste the app's installation instructions (if available) + - **Dependencies**: What packages does it need? (Node, Python, Java, PostgreSQL, etc.) + - **Ports**: What port does it listen on? (e.g., 3000, 8080, 5000) + - **Configuration**: Any environment variables or config files? + +3. **Tell the AI Assistant** + + Share with the AI: + - The repository URL + - The Dockerfile or install instructions + - Link to [docs/contribution/AI.md](AI.md) with instructions to follow + + **Example prompt:** + + ``` + I want to contribute a container script for MyApp to ProxmoxVE. + Repository: https://github.com/owner/myapp + + Here's the Dockerfile: + [paste Dockerfile content] + + Please follow the guidelines in docs/contribution/AI.md to create: + 1. ct/myapp.sh (container script) + 2. install/myapp-install.sh (installation script) + 3. frontend/public/json/myapp.json (metadata) + ``` + +4. **AI Will Generate** + + The AI will produce scripts that: + - Follow all ProxmoxVE patterns and conventions + - Use helper functions from `tools.func` correctly + - Include proper error handling and messages + - Have correct update mechanisms + - Are ready to submit as a PR + +### Key Points for AI Assistants + +- **Templates Location**: `docs/contribution/templates_ct/AppName.sh`, `templates_install/`, `templates_json/` +- **Guidelines**: Must follow `docs/contribution/AI.md` exactly +- **Helper Functions**: Use only functions from `misc/tools.func` - never write custom ones +- **Testing**: Always include `bash ct/myapp.sh` testing before submission +- **No Docker**: Container scripts must be bare-metal, not Docker-based + +### Benefits + +- **Speed**: AI generates boilerplate in seconds +- **Consistency**: Follows same patterns as 200+ existing scripts +- **Quality**: Less bugs and more maintainable code +- **Learning**: See how your app should be structured + +--- ### Documentation @@ -229,7 +447,6 @@ git push origin feature/my-feature ``` 3. **Check code standards** - - [ ] Follows template structure - [ ] Proper error handling - [ ] Documentation updated (if needed) @@ -260,23 +477,48 @@ Before opening a PR: ## ❓ FAQ -### How do I test my changes? +### ⚠️ Why must I use `bash ct/myapp.sh` (during development)? + +During **local development and testing** in your fork, use bash explicitly: ```bash -# For container scripts +# ✅ CORRECT (during development in your fork) +bash ct/myapp.sh + +# ❌ WRONG - Will fail +./ct/myapp.sh +sh ct/myapp.sh +/path/to/ct/myapp.sh +``` + +**Why?** +- Scripts use bash-specific features (arrays, process substitution, etc.) +- Permissions might not be executable on Windows/WSL +- Source files need proper `<(curl ...)` process substitution +- Error handling requires specific bash settings + +**⚠️ But remember:** Once merged, users will run it via `curl | bash` from GitHub, not locally! + +### How do I test my changes locally? + +```bash +# You're on Proxmox VE host with your fork cloned +# Test your script before PR: + bash ct/my-app.sh -# For install scripts (runs inside container) -# The ct script will call it automatically +# The setup-fork.sh script ensures curl pulls from YOUR fork, not upstream +# So this tests your actual changes! -# For advanced debugging +# For advanced debugging with verbose output VERBOSE=yes bash ct/my-app.sh +DEV_MODE_LOGS=true bash ct/my-app.sh ``` ### What if my PR has conflicts? ```bash -# Sync with upstream +# Sync with upstream main repository git fetch upstream git rebase upstream/main @@ -288,17 +530,25 @@ git push -f origin your-branch ### How do I keep my fork updated? -See "Keep Your Fork Updated" section above, or run: +Two ways: +**Option 1: Run setup script again** ```bash bash docs/contribution/setup-fork.sh ``` +**Option 2: Manual sync** +```bash +git fetch upstream +git rebase upstream/main +git push -f origin main +``` + ### Where do I ask questions? - **GitHub Issues**: For bugs and feature requests -- **GitHub Discussions**: For general questions -- **Discord**: Community-scripts server +- **GitHub Discussions**: For general questions and ideas +- **Discord**: Community-scripts server for real-time chat --- @@ -307,7 +557,7 @@ bash docs/contribution/setup-fork.sh ### For First-Time Contributors 1. Read: [docs/README.md](../README.md) - Documentation overview -2. Read: [docs/contribution/FORK_SETUP.md](FORK_SETUP.md) - Fork setup guide +2. Read: [CONTRIBUTING.md](CONTRIBUTING.md) - Essential coding standards 3. Choose your path: - Containers → [docs/ct/DETAILED_GUIDE.md](../ct/DETAILED_GUIDE.md) - Installation → [docs/install/DETAILED_GUIDE.md](../install/DETAILED_GUIDE.md) @@ -318,14 +568,16 @@ bash docs/contribution/setup-fork.sh 1. Review [CONTRIBUTING.md](CONTRIBUTING.md) - Coding standards 2. Review [CODE_AUDIT.md](CODE_AUDIT.md) - Audit checklist -3. Check templates in `/ct/` and `/install/` -4. Submit PR with confidence +3. Check templates in `/docs/contribution/templates_*/` +4. Use AI assistants with [AI.md](AI.md) for code generation +5. Submit PR with confidence -### For Reviewers/Maintainers +### For Using AI Assistants -1. Use [CODE_AUDIT.md](CODE_AUDIT.md) as review guide -2. Reference [docs/TECHNICAL_REFERENCE.md](../TECHNICAL_REFERENCE.md) for architecture -3. Check [docs/EXIT_CODES.md](../EXIT_CODES.md) for error handling +See "Using AI Assistants" section above for: +- How to structure prompts +- What information to provide +- How to validate AI output --- @@ -345,9 +597,9 @@ bash docs/contribution/setup-fork.sh ## 📞 Contact & Support -- **GitHub**: https://github.com/community-scripts/ProxmoxVE -- **Issues**: https://github.com/community-scripts/ProxmoxVE/issues -- **Discussions**: https://github.com/community-scripts/ProxmoxVE/discussions +- **GitHub**: [community-scripts/ProxmoxVE](https://github.com/community-scripts/ProxmoxVE) +- **Issues**: [GitHub Issues](https://github.com/community-scripts/ProxmoxVE/issues) +- **Discussions**: [GitHub Discussions](https://github.com/community-scripts/ProxmoxVE/discussions) - **Discord**: [Join Server](https://discord.gg/UHrpNWGwkH) --- diff --git a/docs/contribution/templates_ct/AppName.sh b/docs/contribution/templates_ct/AppName.sh index 28080b7ed..369eb424c 100644 --- a/docs/contribution/templates_ct/AppName.sh +++ b/docs/contribution/templates_ct/AppName.sh @@ -5,59 +5,109 @@ source <(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxV # License: MIT | https://github.com/community-scripts/ProxmoxVE/raw/main/LICENSE # Source: [SOURCE_URL e.g. https://github.com/example/app] -# App Default Values +# ============================================================================ +# APP CONFIGURATION +# ============================================================================ +# These values are sent to build.func and define default container resources. +# Users can customize these during installation via the interactive prompts. +# ============================================================================ + APP="[AppName]" -var_tags="${var_tags:-[category1];[category2]}" -var_cpu="${var_cpu:-2}" -var_ram="${var_ram:-2048}" -var_disk="${var_disk:-8}" -var_os="${var_os:-debian}" -var_version="${var_version:-13}" -var_unprivileged="${var_unprivileged:-1}" +var_tags="${var_tags:-[category1];[category2]}" # Max 2 tags, semicolon-separated +var_cpu="${var_cpu:-2}" # CPU cores: 1-4 typical +var_ram="${var_ram:-2048}" # RAM in MB: 512, 1024, 2048, etc. +var_disk="${var_disk:-8}" # Disk in GB: 6, 8, 10, 20 typical +var_os="${var_os:-debian}" # OS: debian, ubuntu, alpine +var_version="${var_version:-13}" # OS Version: 13 (Debian), 24.04 (Ubuntu), 3.21 (Alpine) +var_unprivileged="${var_unprivileged:-1}" # 1=unprivileged (secure), 0=privileged (for Docker/Podman) -# ============================================================================= -# CONFIGURATION GUIDE -# ============================================================================= -# APP - Display name, title case (e.g. "Koel", "Wallabag", "Actual Budget") -# var_tags - Max 2 tags, semicolon separated (e.g. "music;streaming", "finance") -# var_cpu - CPU cores: 1-4 typical, 4+ for heavy apps -# var_ram - RAM in MB: 512, 1024, 2048, 4096, 8192 typical -# var_disk - Disk in GB: 6, 8, 10, 20 typical (more for data-heavy apps) -# var_os - OS: debian, ubuntu, alpine -# var_version - OS version: 13 (debian), 24.04 (ubuntu), 3.21 (alpine) -# var_unprivileged - 1 = unprivileged (secure, default), 0 = privileged (for podman/docker) +# ============================================================================ +# INITIALIZATION - These are required in all CT scripts +# ============================================================================ +header_info "$APP" # Display app name and setup header +variables # Initialize build.func variables +color # Load color variables for output +catch_errors # Enable error handling with automatic exit on failure -header_info "$APP" -variables -color -catch_errors +# ============================================================================ +# UPDATE SCRIPT - Called when user selects "Update" from web interface +# ============================================================================ +# This function is triggered by the web interface to update the application. +# It should: +# 1. Check if installation exists +# 2. Check for new GitHub releases +# 3. Stop running services +# 4. Backup critical data +# 5. Deploy new version +# 6. Run post-update commands (migrations, config updates, etc.) +# 7. Restore data if needed +# 8. Start services +# +# Exit with `exit` at the end to prevent container restart. +# ============================================================================ function update_script() { header_info check_container_storage check_container_resources + # Step 1: Verify installation exists if [[ ! -d /opt/[appname] ]]; then msg_error "No ${APP} Installation Found!" exit fi - if check_for_gh_release "[appname]" "[owner/repo]"; then + # Step 2: Check if update is available + if check_for_gh_release "[appname]" "YourUsername/YourRepo"; then + + # Step 3: Stop services before update msg_info "Stopping Service" systemctl stop [appname] msg_ok "Stopped Service" + # Step 4: Backup critical data before overwriting msg_info "Backing up Data" cp -r /opt/[appname]/data /opt/[appname]_data_backup 2>/dev/null || true msg_ok "Backed up Data" - CLEAN_INSTALL=1 fetch_and_deploy_gh_release "[appname]" "[owner/repo]" "tarball" "latest" "/opt/[appname]" + # Step 5: Download and deploy new version + # CLEAN_INSTALL=1 removes old directory before extracting + CLEAN_INSTALL=1 fetch_and_deploy_gh_release "[appname]" "YourUsername/YourRepo" "tarball" "latest" "/opt/[appname]" + # Step 6: Run post-update commands (uncomment as needed) + # These examples show common patterns - use what applies to your app: + # + # For Node.js apps: + # msg_info "Installing Dependencies" + # cd /opt/[appname] + # $STD npm ci --production + # msg_ok "Installed Dependencies" + # + # For Python apps: + # msg_info "Installing Dependencies" + # cd /opt/[appname] + # $STD uv sync --frozen + # msg_ok "Installed Dependencies" + # + # For database migrations: + # msg_info "Running Database Migrations" + # cd /opt/[appname] + # $STD npm run migrate + # msg_ok "Ran Database Migrations" + # + # For PHP apps: + # msg_info "Installing Dependencies" + # cd /opt/[appname] + # $STD composer install --no-dev + # msg_ok "Installed Dependencies" + + # Step 7: Restore data from backup msg_info "Restoring Data" cp -r /opt/[appname]_data_backup/. /opt/[appname]/data/ 2>/dev/null || true rm -rf /opt/[appname]_data_backup msg_ok "Restored Data" + # Step 8: Restart service with new version msg_info "Starting Service" systemctl start [appname] msg_ok "Started Service" @@ -66,10 +116,22 @@ function update_script() { exit } +# ============================================================================ +# MAIN EXECUTION - Container creation flow +# ============================================================================ +# These are called by build.func and handle the full installation process: +# 1. start - Initialize container creation +# 2. build_container - Execute the install script inside container +# 3. description - Display completion info and access details +# ============================================================================ + start build_container description +# ============================================================================ +# COMPLETION MESSAGE +# ============================================================================ msg_ok "Completed successfully!\n" echo -e "${CREATING}${GN}${APP} setup has been successfully initialized!${CL}" echo -e "${INFO}${YW} Access it using the following URL:${CL}"