mirror of
https://github.com/community-scripts/ProxmoxVE.git
synced 2026-02-05 04:43:26 +01:00
Update contribution docs for improved workflow and clarity
Revised multiple documentation files to clarify the recommended development workflow: contributors must test scripts via curl from their GitHub fork (not local bash), use setup-fork.sh for URL rewriting, and submit only new files using cherry-pick. Expanded and modernized install and JSON metadata template guides, emphasizing use of helper functions, resource requirements, and the JSON generator tool. Added detailed step-by-step instructions, best practices, and updated examples throughout.
This commit is contained in:
CanbiZ
@@ -168,9 +168,9 @@ cleanup_lxc
|
||||
|
||||
### Release Management
|
||||
|
||||
| Function | Description | Example |
|
||||
| ----------------------------- | ----------------------------------- | --------------------------------------------------------- |
|
||||
| `fetch_and_deploy_gh_release` | Fetches and installs GitHub Release | `fetch_and_deploy_gh_release "app" "owner/repo"` |
|
||||
| Function | Description | Example |
|
||||
| ----------------------------- | ----------------------------------- | ------------------------------------------------------------- |
|
||||
| `fetch_and_deploy_gh_release` | Fetches and installs GitHub Release | `fetch_and_deploy_gh_release "app" "owner/repo"` |
|
||||
| `check_for_gh_release` | Checks for new version | `if check_for_gh_release "app" "YourUsername/YourRepo"; then` |
|
||||
|
||||
**Modes for `fetch_and_deploy_gh_release`:**
|
||||
@@ -816,7 +816,11 @@ Or no credentials:
|
||||
1. **ALWAYS search `tools.func` first** before implementing custom solutions
|
||||
2. **Use recent scripts as reference** (Thingsboard, UniFi OS, Trip, Flatnotes, etc.)
|
||||
3. **Ask when uncertain** instead of introducing wrong patterns
|
||||
4. **Test locally** - try running scripts in test containers
|
||||
4. **Test via GitHub** - push to your fork and test with curl (not local bash)
|
||||
```bash
|
||||
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 files
|
||||
```
|
||||
5. **Consistency > Creativity** - follow established patterns strictly
|
||||
6. **Check the templates** - they show the correct structure
|
||||
7. **Don't wrap tools.func functions** - they handle their own msg_info/msg_ok output
|
||||
|
||||
@@ -81,11 +81,22 @@ git clone https://github.com/yourUserName/ForkName
|
||||
git switch -c your-feature-branch
|
||||
```
|
||||
|
||||
### 4. Change paths in build.func install.func and AppName.sh
|
||||
### 4. Run setup-fork.sh to auto-configure your fork
|
||||
|
||||
To be able to develop from your own branch you need to change `https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main` to `https://raw.githubusercontent.com/[USER]/[REPOSITORY]/refs/heads/[BRANCH]`. You need to make this change atleast in misc/build.func misc/install.func and in your ct/AppName.sh. This change is only for testing. Before opening a Pull Request you should change this line change all this back to point to `https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main`.
|
||||
```bash
|
||||
bash docs/contribution/setup-fork.sh
|
||||
```
|
||||
|
||||
### 4. Commit changes (without build.func and install.func!)
|
||||
This script automatically:
|
||||
|
||||
- Detects your GitHub username
|
||||
- Updates ALL curl URLs to point to your fork (for testing)
|
||||
- Creates `.git-setup-info` with your config
|
||||
- Backs up all modified files (\*.backup)
|
||||
|
||||
**IMPORTANT**: This modifies 600+ files! Use cherry-pick when submitting your PR (see below).
|
||||
|
||||
### 5. Commit ONLY your new application files
|
||||
|
||||
```bash
|
||||
git commit -m "Your commit message"
|
||||
@@ -97,9 +108,42 @@ git commit -m "Your commit message"
|
||||
git push origin your-feature-branch
|
||||
```
|
||||
|
||||
### 6. Create a Pull Request
|
||||
### 6. Cherry-Pick: Submit Only Your Files for PR
|
||||
|
||||
Open a Pull Request from your feature branch to the main repository branch. You must only include your **$AppName.sh**, **$AppName-install.sh** and **$AppName.json** files in the pull request.
|
||||
⚠️ **IMPORTANT**: setup-fork.sh modified 600+ files. You MUST only submit your 3 new files!
|
||||
|
||||
See [README.md - Cherry-Pick Guide](README.md#-cherry-pick-submitting-only-your-changes) for step-by-step instructions.
|
||||
|
||||
Quick version:
|
||||
|
||||
```bash
|
||||
# Create clean branch from upstream
|
||||
git fetch upstream
|
||||
git checkout -b submit/myapp upstream/main
|
||||
|
||||
# Copy only your files
|
||||
cp ../your-work-branch/ct/myapp.sh ct/myapp.sh
|
||||
cp ../your-work-branch/install_scripts/myapp-install.sh install_scripts/myapp-install.sh
|
||||
cp ../your-work-branch/config/myapp.json config/myapp.json
|
||||
|
||||
# Commit and verify
|
||||
git add ct/myapp.sh install_scripts/myapp-install.sh config/myapp.json
|
||||
git commit -m "feat: add MyApp"
|
||||
git diff upstream/main --name-only # Should show ONLY your 3 files
|
||||
|
||||
# Push and create PR
|
||||
git push origin submit/myapp
|
||||
```
|
||||
|
||||
### 7. Create a Pull Request
|
||||
|
||||
Open a Pull Request from `submit/myapp` → `community-scripts/ProxmoxVE/main`.
|
||||
|
||||
Verify the PR shows ONLY these 3 files:
|
||||
|
||||
- `ct/myapp.sh`
|
||||
- `install_scripts/myapp-install.sh`
|
||||
- `config/myapp.json`
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -38,14 +38,17 @@ source <(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxV
|
||||
```
|
||||
|
||||
**WITHOUT setup-fork.sh:**
|
||||
|
||||
- Script URLs still point to `community-scripts/ProxmoxVE/main`
|
||||
- When you test `bash ct/myapp.sh` locally, it downloads from the **upstream** repo, not your changes
|
||||
- Your modifications aren't actually being tested! ❌
|
||||
- If you test locally with `bash ct/myapp.sh`, you're testing local files, but the script's curl commands would download from **upstream** repo
|
||||
- Your modifications aren't actually being tested via the curl commands! ❌
|
||||
|
||||
**AFTER setup-fork.sh:**
|
||||
|
||||
- Script URLs are updated to `YourUsername/ProxmoxVE/main`
|
||||
- When you test `bash ct/myapp.sh` locally, it downloads from **your fork**
|
||||
- You're actually testing your changes! ✅
|
||||
- When you test via curl from GitHub: `bash -c "$(curl ... YOUR_USERNAME/ProxmoxVE/main/ct/myapp.sh)"`, it downloads from **your fork**
|
||||
- The script's curl commands also point to your fork, so you're actually testing your changes! ✅
|
||||
- ⏱️ **Important:** GitHub takes 10-30 seconds to recognize pushed files - wait before testing!
|
||||
|
||||
```bash
|
||||
# Example: What setup-fork.sh changes
|
||||
|
||||
@@ -51,28 +51,29 @@ cat .git-setup-info
|
||||
# 1. Create feature branch
|
||||
git checkout -b add/my-awesome-app
|
||||
|
||||
# 2. Create application scripts
|
||||
cp ct/example.sh ct/myapp.sh
|
||||
cp install/example-install.sh install/myapp-install.sh
|
||||
# 2. Create application scripts from templates
|
||||
cp docs/contribution/templates_ct/AppName.sh ct/myapp.sh
|
||||
cp docs/contribution/templates_install/AppName-install.sh install_scripts/myapp-install.sh
|
||||
cp docs/contribution/templates_json/AppName.json config/myapp.json
|
||||
|
||||
# 3. Edit your scripts
|
||||
nano ct/myapp.sh
|
||||
nano install/myapp-install.sh
|
||||
nano install_scripts/myapp-install.sh
|
||||
nano config/myapp.json
|
||||
|
||||
# 4. Test locally
|
||||
bash ct/myapp.sh # Will prompt for container creation
|
||||
|
||||
# 5. Commit and push
|
||||
git add ct/myapp.sh install/myapp-install.sh
|
||||
git commit -m "feat: add MyApp container"
|
||||
# 4. Commit and push to your fork
|
||||
git add ct/myapp.sh install_scripts/myapp-install.sh config/myapp.json
|
||||
git commit -m "feat: add MyApp container and install scripts"
|
||||
git push origin add/my-awesome-app
|
||||
|
||||
# 6. Open Pull Request on GitHub
|
||||
# Click: New Pull Request (GitHub will show this automatically)
|
||||
# 5. Test via curl from your fork (GitHub may take 10-30 seconds)
|
||||
bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/ct/myapp.sh)"
|
||||
|
||||
# 7. Keep your fork updated
|
||||
git fetch upstream
|
||||
git rebase upstream/main
|
||||
# 6. Use cherry-pick to submit only your files (see Cherry-Pick section)
|
||||
# DO NOT submit the 600+ files modified by setup-fork.sh!
|
||||
|
||||
# 7. Open Pull Request on GitHub
|
||||
# Create PR from: your-fork/add/my-awesome-app → community-scripts/ProxmoxVE/main
|
||||
```
|
||||
|
||||
**💡 Tip**: See `../FORK_SETUP.md` for detailed fork setup and troubleshooting
|
||||
@@ -137,6 +138,7 @@ Examples:
|
||||
```
|
||||
|
||||
**Rules**:
|
||||
|
||||
- Container script name: **Title Case** (PiHole, Docker, NextCloud)
|
||||
- Install script name: **lowercase** with **hyphens** (pihole-install, docker-install)
|
||||
- Must match: `ct/AppName.sh` ↔ `install/appname-install.sh`
|
||||
@@ -156,6 +158,7 @@ Examples:
|
||||
- Ubuntu 20.04 / Debian 11+ on host
|
||||
|
||||
2. **Git** installed
|
||||
|
||||
```bash
|
||||
apt-get install -y git
|
||||
```
|
||||
@@ -241,18 +244,21 @@ bash -n install/myapp-install.sh
|
||||
### Step 1: Choose Your Template
|
||||
|
||||
**For Simple Web Apps** (Node.js, Python, PHP):
|
||||
|
||||
```bash
|
||||
cp ct/example.sh ct/myapp.sh
|
||||
cp install/example-install.sh install/myapp-install.sh
|
||||
```
|
||||
|
||||
**For Database Apps** (PostgreSQL, MongoDB):
|
||||
|
||||
```bash
|
||||
cp ct/docker.sh ct/myapp.sh # Use Docker container
|
||||
# OR manual setup for more control
|
||||
```
|
||||
|
||||
**For Alpine Linux Apps** (lightweight):
|
||||
|
||||
```bash
|
||||
# Use ct/alpine.sh as reference
|
||||
# Edit install script to use Alpine packages (apk not apt)
|
||||
@@ -317,6 +323,7 @@ echo -e "${TAB}${GATEWAY}${BGN}http://${IP}:PORT${CL}"
|
||||
```
|
||||
|
||||
**Checklist**:
|
||||
|
||||
- [ ] APP variable matches filename
|
||||
- [ ] var_tags semicolon-separated (no spaces)
|
||||
- [ ] Realistic CPU/RAM/disk values
|
||||
@@ -370,6 +377,7 @@ cleanup_lxc
|
||||
```
|
||||
|
||||
**Checklist**:
|
||||
|
||||
- [ ] Functions loaded from `$FUNCTIONS_FILE_PATH`
|
||||
- [ ] All installation phases present (deps, tools, app, config, cleanup)
|
||||
- [ ] Using `$STD` for output suppression
|
||||
@@ -774,16 +782,19 @@ Use this template:
|
||||
|
||||
```markdown
|
||||
## Description
|
||||
|
||||
Brief description of what this PR adds/fixes
|
||||
|
||||
## Type of Change
|
||||
|
||||
- [ ] New application (ct/AppName.sh + install/appname-install.sh)
|
||||
- [ ] Update existing application
|
||||
- [ ] Bug fix
|
||||
- [ ] Documentation update
|
||||
- [ ] Other: _______
|
||||
- [ ] Other: **\_\_\_**
|
||||
|
||||
## Testing
|
||||
|
||||
- [ ] Tested on Proxmox VE 8.x
|
||||
- [ ] Container creation successful
|
||||
- [ ] Application installation successful
|
||||
@@ -792,6 +803,7 @@ Brief description of what this PR adds/fixes
|
||||
- [ ] No temporary files left after installation
|
||||
|
||||
## Application Details (for new apps only)
|
||||
|
||||
- **App Name**: MyApp
|
||||
- **Source**: https://github.com/app/repo
|
||||
- **Default OS**: Debian 12
|
||||
@@ -800,6 +812,7 @@ Brief description of what this PR adds/fixes
|
||||
- **Access URL**: http://IP:PORT/path
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] My code follows the style guidelines
|
||||
- [ ] I have performed a self-review
|
||||
- [ ] I have tested the script locally
|
||||
@@ -811,6 +824,7 @@ Brief description of what this PR adds/fixes
|
||||
### Step 5: Respond to Review Comments
|
||||
|
||||
**Maintainers may request changes**:
|
||||
|
||||
- Fix syntax/style issues
|
||||
- Add better error handling
|
||||
- Optimize resource usage
|
||||
@@ -922,6 +936,7 @@ pct exec CTID netstat -tlnp | grep LISTEN
|
||||
### Q: Can I test without a Proxmox system?
|
||||
|
||||
**A**: Partially. You can verify syntax and ShellCheck compliance locally, but real container testing requires Proxmox. Consider using:
|
||||
|
||||
- Proxmox in a VM (VirtualBox/KVM)
|
||||
- Test instances on Hetzner/DigitalOcean
|
||||
- Ask maintainers to test for you
|
||||
@@ -929,6 +944,7 @@ pct exec CTID netstat -tlnp | grep LISTEN
|
||||
### Q: My update function is very complex - is that OK?
|
||||
|
||||
**A**: Yes! Update functions can be complex if needed. Just ensure:
|
||||
|
||||
- Backup user data before updating
|
||||
- Restore user data after update
|
||||
- Test thoroughly before submitting
|
||||
@@ -937,6 +953,7 @@ pct exec CTID netstat -tlnp | grep LISTEN
|
||||
### Q: Can I add new dependencies to build.func?
|
||||
|
||||
**A**: Generally no. build.func is the orchestrator and should remain stable. New functions should go in:
|
||||
|
||||
- `tools.func` - Tool installation
|
||||
- `core.func` - Utility functions
|
||||
- `install.func` - Container setup
|
||||
@@ -948,11 +965,13 @@ Ask in an issue first if you're unsure.
|
||||
**A**: You have options:
|
||||
|
||||
**Option 1**: Use Advanced mode (19-step wizard)
|
||||
|
||||
```bash
|
||||
# Extend advanced_settings() if app needs special vars
|
||||
```
|
||||
|
||||
**Option 2**: Create custom setup menu
|
||||
|
||||
```bash
|
||||
function custom_config() {
|
||||
OPTION=$(whiptail --inputbox "Enter database name:" 8 60)
|
||||
@@ -961,6 +980,7 @@ function custom_config() {
|
||||
```
|
||||
|
||||
**Option 3**: Leave as defaults + documentation
|
||||
|
||||
```bash
|
||||
# In success message:
|
||||
echo "Edit /opt/myapp/config.json to customize settings"
|
||||
@@ -969,9 +989,10 @@ echo "Edit /opt/myapp/config.json to customize settings"
|
||||
### Q: Can I contribute Windows/macOS/ARM support?
|
||||
|
||||
**A**:
|
||||
|
||||
- **Windows**: Not planned (ProxmoxVE is Linux/Proxmox focused)
|
||||
- **macOS**: Can contribute Docker-based alternatives
|
||||
- **ARM**: Yes! Many apps work on ARM. Add to vm/pimox-*.sh scripts
|
||||
- **ARM**: Yes! Many apps work on ARM. Add to vm/pimox-\*.sh scripts
|
||||
|
||||
---
|
||||
|
||||
@@ -995,6 +1016,7 @@ echo "Edit /opt/myapp/config.json to customize settings"
|
||||
### Report Bugs
|
||||
|
||||
When reporting bugs, include:
|
||||
|
||||
- Which application
|
||||
- What happened (error message)
|
||||
- What you expected
|
||||
@@ -1002,6 +1024,7 @@ When reporting bugs, include:
|
||||
- Container OS and version
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
Title: pihole-install.sh fails on Alpine 3.20
|
||||
|
||||
@@ -1025,6 +1048,7 @@ Error Output:
|
||||
## Contribution Statistics
|
||||
|
||||
**ProxmoxVE by the Numbers**:
|
||||
|
||||
- 🎯 40+ applications supported
|
||||
- 👥 100+ contributors
|
||||
- 📊 10,000+ GitHub stars
|
||||
@@ -1038,6 +1062,7 @@ Error Output:
|
||||
## Code of Conduct
|
||||
|
||||
By contributing, you agree to:
|
||||
|
||||
- ✅ Be respectful and inclusive
|
||||
- ✅ Follow the style guidelines
|
||||
- ✅ Test your changes thoroughly
|
||||
|
||||
@@ -45,17 +45,18 @@ 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 locally (in your fork before PR)
|
||||
bash ct/myapp.sh
|
||||
# ⚠️ Important: Always use `bash ct/myapp.sh`, NOT `./ct/myapp.sh`
|
||||
# 7. Push to your fork and test via GitHub
|
||||
git push origin feature/my-awesome-app
|
||||
bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/ct/myapp.sh)"
|
||||
# ⏱️ GitHub may take 10-30 seconds to update files - be patient!
|
||||
|
||||
# 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`
|
||||
# 9. Test the install script (if you created one)
|
||||
bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/install_scripts/myapp-install.sh)"
|
||||
# ⏱️ GitHub may take 10-30 seconds to update files - be patient!
|
||||
|
||||
# 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
|
||||
@@ -84,15 +85,18 @@ bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/Proxmo
|
||||
### Development vs. Production Execution
|
||||
|
||||
**During Development (you, in your fork):**
|
||||
```bash
|
||||
# You test locally with your cloned files
|
||||
bash ct/myapp.sh
|
||||
|
||||
# The script's curl commands are updated by setup-fork.sh to pull from YOUR fork
|
||||
```bash
|
||||
# You MUST test via curl from your GitHub fork (not local files!)
|
||||
bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/ct/myapp.sh)"
|
||||
|
||||
# The script's curl commands are updated by setup-fork.sh to point to YOUR fork
|
||||
# This ensures you're testing your actual changes
|
||||
# ⏱️ Wait 10-30 seconds after pushing - GitHub updates slowly
|
||||
```
|
||||
|
||||
**After Merge (users, from GitHub):**
|
||||
|
||||
```bash
|
||||
# Users download the script from upstream via curl
|
||||
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/myapp.sh)"
|
||||
@@ -102,8 +106,9 @@ bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/Proxmo
|
||||
```
|
||||
|
||||
**Summary:**
|
||||
- **Development**: `bash ct/myapp.sh` (local clone) → setup-fork.sh changes curl URLs to your fork
|
||||
- **Production**: `curl | bash` from upstream → curl URLs point to community-scripts repo
|
||||
|
||||
- **Development**: Push to fork, test via curl → setup-fork.sh changes curl URLs to your fork
|
||||
- **Production**: curl | bash from upstream → curl URLs point to community-scripts repo
|
||||
|
||||
---
|
||||
|
||||
@@ -137,8 +142,10 @@ Without running this script, all links in your fork will still point to the upst
|
||||
|
||||
Your fork is fully configured and ready to develop. You can:
|
||||
|
||||
- Test changes locally with `bash ct/myapp.sh`
|
||||
- Push changes to your fork
|
||||
- Test via curl: `bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/ct/myapp.sh)"`
|
||||
- All links will reference your fork for development
|
||||
- ⏱️ Wait 10-30 seconds after pushing - GitHub takes time to update
|
||||
- Commit and push with confidence
|
||||
- Create a PR to merge into upstream
|
||||
|
||||
@@ -185,7 +192,7 @@ All scripts and configurations must follow our coding standards to ensure consis
|
||||
- ✅ Include proper shebang: `#!/usr/bin/env bash`
|
||||
- ✅ Add copyright header with author
|
||||
- ✅ Handle errors properly with `msg_error`, `msg_ok`, etc.
|
||||
- ✅ Test before submitting PR
|
||||
- ✅ Test before submitting PR (via curl from your fork, not local bash)
|
||||
- ✅ Update documentation if needed
|
||||
|
||||
---
|
||||
@@ -357,7 +364,11 @@ If you're using **Visual Studio Code** with an AI assistant, you can leverage ou
|
||||
- **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
|
||||
- **Testing**: Always test before submission via curl from your fork
|
||||
```bash
|
||||
bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/ct/myapp.sh)"
|
||||
# Wait 10-30 seconds after pushing changes
|
||||
```
|
||||
- **No Docker**: Container scripts must be bare-metal, not Docker-based
|
||||
|
||||
### Benefits
|
||||
@@ -455,11 +466,12 @@ git push origin feature/my-feature
|
||||
git rebase upstream/main
|
||||
```
|
||||
|
||||
2. **Test your changes**
|
||||
2. **Test your changes** (via curl from your fork)
|
||||
|
||||
```bash
|
||||
bash ct/my-app.sh
|
||||
bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/ct/my-app.sh)"
|
||||
# Follow prompts and test the container
|
||||
# ⏱️ Wait 10-30 seconds after pushing - GitHub takes time to update
|
||||
```
|
||||
|
||||
3. **Check code standards**
|
||||
@@ -493,44 +505,61 @@ Before opening a PR:
|
||||
|
||||
## ❓ FAQ
|
||||
|
||||
### ⚠️ Why must I use `bash ct/myapp.sh` (during development)?
|
||||
### ❌ Why can't I test with `bash ct/myapp.sh` locally?
|
||||
|
||||
During **local development and testing** in your fork, use bash explicitly:
|
||||
You might try:
|
||||
|
||||
```bash
|
||||
# ✅ CORRECT (during development in your fork)
|
||||
# ❌ WRONG - This won't test your actual changes!
|
||||
bash ct/myapp.sh
|
||||
|
||||
# ❌ WRONG - Will fail
|
||||
./ct/myapp.sh
|
||||
sh ct/myapp.sh
|
||||
/path/to/ct/myapp.sh
|
||||
```
|
||||
|
||||
**Why this fails:**
|
||||
|
||||
- `bash ct/myapp.sh` uses the LOCAL clone file
|
||||
- The LOCAL file doesn't execute the curl commands - it's already on disk
|
||||
- The curl URLs INSIDE the script are modified by setup-fork.sh, but they're not executed
|
||||
- So you can't verify if your curl URLs actually work
|
||||
- Users will get the curl URL version (which may be broken)
|
||||
|
||||
**Solution:** Always test via curl from GitHub:
|
||||
|
||||
```bash
|
||||
# ✅ CORRECT - Tests the actual GitHub URLs
|
||||
bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/ct/myapp.sh)"
|
||||
```
|
||||
|
||||
### ❓ How do I test my changes?
|
||||
|
||||
You **cannot** test locally with `bash ct/myapp.sh` from your cloned directory!
|
||||
|
||||
You **must** push to GitHub and test via curl from your fork:
|
||||
|
||||
```bash
|
||||
# 1. Push your changes to your fork
|
||||
git push origin feature/my-awesome-app
|
||||
|
||||
# 2. Test via curl (this loads the script from GitHub, not local files)
|
||||
bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/ct/my-app.sh)"
|
||||
|
||||
# 3. For verbose/debug output, pass environment variables
|
||||
VERBOSE=yes bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/ct/my-app.sh)"
|
||||
DEV_MODE_LOGS=true bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/ct/my-app.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
|
||||
- Local `bash ct/myapp.sh` uses local files from your clone
|
||||
- But the script's INTERNAL curl commands have been modified by setup-fork.sh to point to your fork
|
||||
- This discrepancy means you're not actually testing the curl URLs
|
||||
- Testing via curl ensures the script downloads from YOUR fork GitHub URLs
|
||||
- ⏱️ **Important:** GitHub takes 10-30 seconds to recognize newly pushed files. Wait before testing!
|
||||
|
||||
**⚠️ But remember:** Once merged, users will run it via `curl | bash` from GitHub, not locally!
|
||||
**What if local bash worked?**
|
||||
|
||||
### 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
|
||||
|
||||
# The setup-fork.sh script ensures curl pulls from YOUR fork, not upstream
|
||||
# So this tests your actual changes!
|
||||
|
||||
# For advanced debugging with verbose output
|
||||
VERBOSE=yes bash ct/my-app.sh
|
||||
DEV_MODE_LOGS=true bash ct/my-app.sh
|
||||
```
|
||||
You'd be testing local files only, not the actual GitHub URLs that users will download. This means broken curl links wouldn't be caught during testing.
|
||||
|
||||
### What if my PR has conflicts?
|
||||
|
||||
|
||||
@@ -1,197 +1,193 @@
|
||||
# **AppName<span></span>.sh Scripts**
|
||||
# CT Container Scripts - Quick Reference
|
||||
|
||||
`AppName.sh` scripts found in the `/ct` directory. These scripts are responsible for the installation of the desired application. For this guide we take `/ct/snipeit.sh` as example.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [**AppName.sh Scripts**](#appnamesh-scripts)
|
||||
- [Table of Contents](#table-of-contents)
|
||||
- [1. **File Header**](#1-file-header)
|
||||
- [1.1 **Shebang**](#11-shebang)
|
||||
- [1.2 **Import Functions**](#12-import-functions)
|
||||
- [1.3 **Metadata**](#13-metadata)
|
||||
- [2 **Variables and function import**](#2-variables-and-function-import)
|
||||
- [2.1 **Default Values**](#21-default-values)
|
||||
- [2.2 **📋 App output \& base settings**](#22--app-output--base-settings)
|
||||
- [2.3 **🛠 Core functions**](#23--core-functions)
|
||||
- [3 **Update function**](#3-update-function)
|
||||
- [3.1 **Function Header**](#31-function-header)
|
||||
- [3.2 **Check APP**](#32-check-app)
|
||||
- [3.3 **Check version**](#33-check-version)
|
||||
- [3.4 **Verbosity**](#34-verbosity)
|
||||
- [3.5 **Backups**](#35-backups)
|
||||
- [3.6 **Cleanup**](#36-cleanup)
|
||||
- [3.7 **No update function**](#37-no-update-function)
|
||||
- [4 **End of the script**](#4-end-of-the-script)
|
||||
- [5. **Contribution checklist**](#5-contribution-checklist)
|
||||
|
||||
## 1. **File Header**
|
||||
|
||||
### 1.1 **Shebang**
|
||||
|
||||
- Use `#!/usr/bin/env bash` as the shebang.
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
```
|
||||
|
||||
### 1.2 **Import Functions**
|
||||
|
||||
- Import the build.func file.
|
||||
- When developing your own script, change the URL to your own repository.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> You also need to change all apperances of this URL in `misc/build.func` and `misc/install.func`
|
||||
|
||||
Example for development:
|
||||
|
||||
```bash
|
||||
source <(curl -fsSL https://raw.githubusercontent.com/[USER]/[REPO]/refs/heads/[BRANCH]/misc/build.func)
|
||||
```
|
||||
|
||||
Final script:
|
||||
|
||||
```bash
|
||||
source <(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/misc/build.func)
|
||||
```
|
||||
|
||||
> [!CAUTION]
|
||||
> Before opening a Pull Request, change the URLs to point to the community-scripts repo.
|
||||
|
||||
### 1.3 **Metadata**
|
||||
|
||||
- Add clear comments for script metadata, including author, copyright, and license information.
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
# Copyright (c) 2021-2026 community-scripts ORG
|
||||
# Author: [YourUserName]
|
||||
# License: MIT | https://github.com/community-scripts/ProxmoxVE/raw/main/LICENSE
|
||||
# Source: [SOURCE_URL]
|
||||
```
|
||||
|
||||
> [!NOTE]:
|
||||
> [!WARNING]
|
||||
> **This is legacy documentation.** Refer to the **modern template** at [templates_ct/AppName.sh](AppName.sh) for best practices.
|
||||
>
|
||||
> - Add your username and source URL
|
||||
> - For existing scripts, add "| Co-Author [YourUserName]" after the current author
|
||||
> Current templates use:
|
||||
>
|
||||
> - `tools.func` helpers instead of manual patterns
|
||||
> - `check_for_gh_release` and `fetch_and_deploy_gh_release` from build.func
|
||||
> - Automatic setup-fork.sh configuration
|
||||
|
||||
---
|
||||
|
||||
## 2 **Variables and function import**
|
||||
>
|
||||
> [!NOTE]
|
||||
> You need to have all this set in your script, otherwise it will not work!
|
||||
## Before Creating a Script
|
||||
|
||||
### 2.1 **Default Values**
|
||||
1. **Fork & Clone:**
|
||||
|
||||
- This section sets the default values for the container.
|
||||
- `APP` needs to be set to the application name and must be equal to the filenames of your scripts.
|
||||
- `var_tags`: You can set Tags for the CT wich show up in the Proxmox UI. Don´t overdo it!
|
||||
```bash
|
||||
git clone https://github.com/YOUR_USERNAME/ProxmoxVE.git
|
||||
cd ProxmoxVE
|
||||
```
|
||||
|
||||
>[!NOTE]
|
||||
>Description for all Default Values
|
||||
>
|
||||
>| Variable | Description | Notes |
|
||||
>|----------|-------------|-------|
|
||||
>| `APP` | Application name | Must match ct\AppName.sh |
|
||||
>| `var_tags` | Proxmox display tags without Spaces, only ; | Limit the number |
|
||||
>| `var_cpu` | CPU cores | Number of cores |
|
||||
>| `var_ram` | RAM | In MB |
|
||||
>| `var_disk` | Disk capacity | In GB |
|
||||
>| `var_os` | Operating system | alpine, debian, ubuntu |
|
||||
>| `var_version` | OS version | e.g., 3.20, 11, 12, 20.04 |
|
||||
>| `var_unprivileged` | Container type | 1 = Unprivileged, 0 = Privileged |
|
||||
2. **Run setup-fork.sh** (updates all curl URLs to your fork):
|
||||
|
||||
Example:
|
||||
```bash
|
||||
bash docs/contribution/setup-fork.sh
|
||||
```
|
||||
|
||||
3. **Copy the Modern Template:**
|
||||
|
||||
```bash
|
||||
cp templates_ct/AppName.sh ct/MyApp.sh
|
||||
# Edit ct/MyApp.sh with your app details
|
||||
```
|
||||
|
||||
4. **Test Your Script (via GitHub):**
|
||||
|
||||
⚠️ **Important:** You must push to GitHub and test via curl, not `bash ct/MyApp.sh`!
|
||||
|
||||
```bash
|
||||
# Push your changes to your fork first
|
||||
git push origin feature/my-awesome-app
|
||||
|
||||
# Then test via curl (this loads from YOUR fork, not local files)
|
||||
bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/ct/MyApp.sh)"
|
||||
```
|
||||
|
||||
> 💡 **Why?** The script's curl commands are modified by setup-fork.sh, but local execution uses local files, not the updated GitHub URLs. Testing via curl ensures your script actually works.
|
||||
>
|
||||
> ⏱️ **Note:** GitHub sometimes takes 10-30 seconds to update files. If you don't see your changes, wait and try again.
|
||||
|
||||
5. **Cherry-Pick for PR** (submit ONLY your 3-4 files):
|
||||
- See [Cherry-Pick Guide](../README.md) for step-by-step git commands
|
||||
|
||||
---
|
||||
|
||||
## Template Structure
|
||||
|
||||
The modern template includes:
|
||||
|
||||
### Header
|
||||
|
||||
```bash
|
||||
APP="SnipeIT"
|
||||
var_tags="asset-management;foss"
|
||||
#!/usr/bin/env bash
|
||||
source <(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/misc/build.func)
|
||||
# (Note: setup-fork.sh changes this URL to point to YOUR fork during development)
|
||||
```
|
||||
|
||||
### Metadata
|
||||
|
||||
```bash
|
||||
# Copyright (c) 2021-2026 community-scripts ORG
|
||||
# Author: YourUsername
|
||||
# License: MIT
|
||||
APP="MyApp"
|
||||
var_tags="app-category;foss"
|
||||
var_cpu="2"
|
||||
var_ram="2048"
|
||||
var_disk="4"
|
||||
var_os="debian"
|
||||
var_version="12"
|
||||
var_os="alpine"
|
||||
var_version="3.20"
|
||||
var_unprivileged="1"
|
||||
```
|
||||
|
||||
## 2.2 **📋 App output & base settings**
|
||||
### Core Setup
|
||||
|
||||
```bash
|
||||
header_info "$APP"
|
||||
```
|
||||
- `header_info`: Generates ASCII header for APP
|
||||
|
||||
## 2.3 **🛠 Core functions**
|
||||
|
||||
```bash
|
||||
variables
|
||||
color
|
||||
catch_errors
|
||||
```
|
||||
|
||||
- `variables`: Processes input and prepares variables
|
||||
- `color`: Sets icons, colors, and formatting
|
||||
- `catch_errors`: Enables error handling
|
||||
### Update Function
|
||||
|
||||
---
|
||||
|
||||
## 3 **Update function**
|
||||
|
||||
### 3.1 **Function Header**
|
||||
|
||||
- If applicable write a function that updates the application and the OS in the container.
|
||||
- Each update function starts with the same code:
|
||||
The modern template provides a standard update pattern:
|
||||
|
||||
```bash
|
||||
function update_script() {
|
||||
header_info
|
||||
check_container_storage
|
||||
check_container_resources
|
||||
```
|
||||
|
||||
### 3.2 **Check APP**
|
||||
|
||||
- Before doing anything update-wise, check if the app is installed in the container.
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
if [[ ! -d /opt/snipe-it ]]; then
|
||||
msg_error "No ${APP} Installation Found!"
|
||||
exit
|
||||
fi
|
||||
```
|
||||
|
||||
### 3.3 **Check version**
|
||||
|
||||
- Before updating, check if a new version exists.
|
||||
- We use the `${APPLICATION}_version.txt` file created in `/opt` during the install to compare new versions against the currently installed version.
|
||||
|
||||
Example with a Github Release:
|
||||
|
||||
```bash
|
||||
RELEASE=$(curl -fsSL https://api.github.com/repos/snipe/snipe-it/releases/latest | grep "tag_name" | awk '{print substr($2, 3, length($2)-4) }')
|
||||
if [[ ! -f /opt/${APP}_version.txt ]] || [[ "${RELEASE}" != "$(cat /opt/${APP}_version.txt)" ]]; then
|
||||
msg_info "Updating ${APP} to v${RELEASE}"
|
||||
#DO UPDATE
|
||||
else
|
||||
msg_ok "No update required. ${APP} is already at v${RELEASE}."
|
||||
fi
|
||||
exit
|
||||
# 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"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Patterns
|
||||
|
||||
### Check for Updates (ProxmoxVE Fork)
|
||||
|
||||
Use `check_for_gh_release` with **YOUR fork**:
|
||||
|
||||
```bash
|
||||
check_for_gh_release "myapp" "YourUsername/ProxmoxVE"
|
||||
```
|
||||
|
||||
### Deploy External App
|
||||
|
||||
Use `fetch_and_deploy_gh_release` with **target app repo**:
|
||||
|
||||
```bash
|
||||
fetch_and_deploy_gh_release "myapp" "myapp/repo" "appname.tar.gz" "latest" "/opt/myapp"
|
||||
```
|
||||
|
||||
### Avoid Manual Version Checking
|
||||
|
||||
❌ OLD (manual):
|
||||
|
||||
```bash
|
||||
RELEASE=$(curl -fsSL https://api.github.com/repos/myapp/myapp/releases/latest | grep tag_name)
|
||||
```
|
||||
|
||||
✅ NEW (use tools.func):
|
||||
|
||||
```bash
|
||||
fetch_and_deploy_gh_release "myapp" "myapp/repo" "appname.tar.gz" "latest" "/opt/myapp"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use tools.func helpers** - Don't manually curl for versions
|
||||
2. **Only add app-specific dependencies** - Don't add ca-certificates, curl, gnupg (handled by build.func)
|
||||
3. **Test via curl from your fork** - Push first, then: `bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/ct/MyApp.sh)"`
|
||||
4. **Wait for GitHub to update** - Takes 10-30 seconds after git push
|
||||
5. **Cherry-pick only YOUR files** - Submit only ct/MyApp.sh, install_scripts/MyApp-install.sh, config/myapp.json (3 files)
|
||||
6. **Verify before PR** - Run `git diff upstream/main --name-only` to confirm only your files changed
|
||||
|
||||
---
|
||||
|
||||
## Common Update Patterns
|
||||
|
||||
See the [modern template](AppName.sh) and [AI.md](../AI.md) for complete working examples.
|
||||
|
||||
Recent reference scripts with good update functions:
|
||||
|
||||
- [Trip](https://github.com/community-scripts/ProxmoxVE/blob/main/ct/trip.sh)
|
||||
- [Thingsboard](https://github.com/community-scripts/ProxmoxVE/blob/main/ct/thingsboard.sh)
|
||||
- [UniFi](https://github.com/community-scripts/ProxmoxVE/blob/main/ct/unifi.sh)
|
||||
|
||||
---
|
||||
|
||||
## Need Help?
|
||||
|
||||
- **[README.md](../README.md)** - Full contribution workflow
|
||||
- **[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
|
||||
}
|
||||
|
||||
````
|
||||
|
||||
### 3.4 **Verbosity**
|
||||
|
||||
- Use the appropriate flag (**-q** in the examples) for a command to suppress its output.
|
||||
Example:
|
||||
Example:
|
||||
|
||||
```bash
|
||||
curl -fsSL
|
||||
unzip -q
|
||||
```
|
||||
````
|
||||
|
||||
- If a command does not come with this functionality use `$STD` to suppress it's output.
|
||||
|
||||
@@ -207,8 +203,8 @@ $STD php artisan config:clear
|
||||
- Backup user data if necessary.
|
||||
- Move all user data back in the directory when the update is finished.
|
||||
|
||||
>[!NOTE]
|
||||
>This is not meant to be a permanent backup
|
||||
> [!NOTE]
|
||||
> This is not meant to be a permanent backup
|
||||
|
||||
Example backup:
|
||||
|
||||
@@ -227,7 +223,7 @@ Example config restore:
|
||||
### 3.6 **Cleanup**
|
||||
|
||||
- Do not forget to remove any temporary files/folders such as zip-files or temporary backups.
|
||||
Example:
|
||||
Example:
|
||||
|
||||
```bash
|
||||
rm -rf /opt/v${RELEASE}.zip
|
||||
@@ -277,7 +273,7 @@ echo -e "${TAB}${GATEWAY}${BGN}http://${IP}${CL}"
|
||||
## 5. **Contribution checklist**
|
||||
|
||||
- [ ] Shebang is correctly set (`#!/usr/bin/env bash`).
|
||||
- [ ] Correct link to *build.func*
|
||||
- [ ] Correct link to _build.func_
|
||||
- [ ] Metadata (author, license) is included at the top.
|
||||
- [ ] Variables follow naming conventions.
|
||||
- [ ] Update function exists.
|
||||
|
||||
@@ -1,54 +1,195 @@
|
||||
# Install Scripts - Quick Reference
|
||||
|
||||
# **AppName<span></span>-install.sh Scripts**
|
||||
> [!WARNING]
|
||||
> **This is legacy documentation.** Refer to the **modern template** at [templates_install/AppName-install.sh](AppName-install.sh) for best practices.
|
||||
>
|
||||
> Current templates use:
|
||||
>
|
||||
> - `tools.func` helpers (setup_nodejs, setup_python, setup_postgresql_db, etc.)
|
||||
> - Automatic dependency installation via build.func
|
||||
> - Standardized environment variable patterns
|
||||
|
||||
`AppName-install.sh` scripts found in the `/install` directory. These scripts are responsible for the installation of the application. For this guide we take `/install/snipeit-install.sh` as example.
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
## Before Creating a Script
|
||||
|
||||
- [**AppName-install.sh Scripts**](#appname-installsh-scripts)
|
||||
- [Table of Contents](#table-of-contents)
|
||||
- [1. **File header**](#1-file-header)
|
||||
- [1.1 **Shebang**](#11-shebang)
|
||||
- [1.2 **Comments**](#12-comments)
|
||||
- [1.3 **Variables and function import**](#13-variables-and-function-import)
|
||||
- [2. **Variable naming and management**](#2-variable-naming-and-management)
|
||||
- [2.1 **Naming conventions**](#21-naming-conventions)
|
||||
- [3. **Dependencies**](#3-dependencies)
|
||||
- [3.1 **Install all at once**](#31-install-all-at-once)
|
||||
- [3.2 **Collapse dependencies**](#32-collapse-dependencies)
|
||||
- [4. **Paths to application files**](#4-paths-to-application-files)
|
||||
- [5. **Version management**](#5-version-management)
|
||||
- [5.1 **Install the latest release**](#51-install-the-latest-release)
|
||||
- [5.2 **Save the version for update checks**](#52-save-the-version-for-update-checks)
|
||||
- [6. **Input and output management**](#6-input-and-output-management)
|
||||
- [6.1 **User feedback**](#61-user-feedback)
|
||||
- [6.2 **Verbosity**](#62-verbosity)
|
||||
- [7. **String/File Manipulation**](#7-stringfile-manipulation)
|
||||
- [7.1 **File Manipulation**](#71-file-manipulation)
|
||||
- [8. **Security practices**](#8-security-practices)
|
||||
- [8.1 **Password generation**](#81-password-generation)
|
||||
- [8.2 **File permissions**](#82-file-permissions)
|
||||
- [9. **Service Configuration**](#9-service-configuration)
|
||||
- [9.1 **Configuration files**](#91-configuration-files)
|
||||
- [9.2 **Credential management**](#92-credential-management)
|
||||
- [9.3 **Enviroment files**](#93-enviroment-files)
|
||||
- [9.4 **Services**](#94-services)
|
||||
- [10. **Cleanup**](#10-cleanup)
|
||||
- [10.1 **Remove temporary files**](#101-remove-temporary-files)
|
||||
- [10.2 **Autoremove and autoclean**](#102-autoremove-and-autoclean)
|
||||
- [11. **Best Practices Checklist**](#11-best-practices-checklist)
|
||||
- [Example: High-Level Script Flow](#example-high-level-script-flow)
|
||||
1. **Copy the Modern Template:**
|
||||
|
||||
## 1. **File header**
|
||||
```bash
|
||||
cp templates_install/AppName-install.sh install_scripts/MyApp-install.sh
|
||||
# Edit install_scripts/MyApp-install.sh
|
||||
```
|
||||
|
||||
### 1.1 **Shebang**
|
||||
2. **Key Pattern:**
|
||||
- CT scripts source build.func and call the install script
|
||||
- Install scripts use sourced FUNCTIONS_FILE_PATH (via build.func)
|
||||
- Both scripts work together in the container
|
||||
|
||||
- Use `#!/usr/bin/env bash` as the shebang.
|
||||
3. **Test via GitHub:**
|
||||
|
||||
```bash
|
||||
# Push your changes to your fork first
|
||||
git push origin feature/my-awesome-app
|
||||
|
||||
# Test the CT script via curl (it will call the install script)
|
||||
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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Template Structure
|
||||
|
||||
### Header
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source <(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/misc/install.func)
|
||||
# (setup-fork.sh modifies this URL to point to YOUR fork during development)
|
||||
```
|
||||
|
||||
### Dependencies (App-Specific Only)
|
||||
|
||||
```bash
|
||||
# Don't add: ca-certificates, curl, gnupg, wget, git, jq
|
||||
# These are handled by build.func
|
||||
msg_info "Installing dependencies"
|
||||
$STD apt-get install -y app-specific-deps
|
||||
msg_ok "Installed dependencies"
|
||||
```
|
||||
|
||||
### Runtime Setup
|
||||
|
||||
Use tools.func helpers instead of manual installation:
|
||||
|
||||
```bash
|
||||
# ✅ NEW (use tools.func):
|
||||
NODE_VERSION="20"
|
||||
setup_nodejs
|
||||
# OR
|
||||
PYTHON_VERSION="3.12"
|
||||
setup_uv
|
||||
# OR
|
||||
PG_DB_NAME="myapp_db"
|
||||
PG_DB_USER="myapp"
|
||||
setup_postgresql_db
|
||||
```
|
||||
|
||||
### Service Configuration
|
||||
|
||||
```bash
|
||||
# Create .env file
|
||||
msg_info "Configuring MyApp"
|
||||
cat << EOF > /opt/myapp/.env
|
||||
DEBUG=false
|
||||
PORT=8080
|
||||
DATABASE_URL=postgresql://...
|
||||
EOF
|
||||
msg_ok "Configuration complete"
|
||||
|
||||
# Create systemd service
|
||||
msg_info "Creating systemd service"
|
||||
cat << EOF > /etc/systemd/system/myapp.service
|
||||
[Unit]
|
||||
Description=MyApp
|
||||
[Service]
|
||||
ExecStart=/usr/bin/node /opt/myapp/app.js
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
EOF
|
||||
msg_ok "Service created"
|
||||
```
|
||||
|
||||
### Finalization
|
||||
|
||||
```bash
|
||||
msg_info "Finalizing MyApp installation"
|
||||
systemctl enable --now myapp
|
||||
motd_ssh
|
||||
customize
|
||||
msg_ok "MyApp installation complete"
|
||||
cleanup_lxc
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Patterns
|
||||
|
||||
### Avoid Manual Version Checking
|
||||
|
||||
❌ OLD (manual):
|
||||
|
||||
```bash
|
||||
RELEASE=$(curl -fsSL https://api.github.com/repos/app/repo/releases/latest | grep tag_name)
|
||||
wget https://github.com/app/repo/releases/download/$RELEASE/app.tar.gz
|
||||
```
|
||||
|
||||
✅ NEW (use tools.func via CT script's fetch_and_deploy_gh_release):
|
||||
|
||||
```bash
|
||||
# In CT script, not install script:
|
||||
fetch_and_deploy_gh_release "myapp" "app/repo" "app.tar.gz" "latest" "/opt/myapp"
|
||||
```
|
||||
|
||||
### Database Setup
|
||||
|
||||
```bash
|
||||
# Use setup_postgresql_db, setup_mysql_db, etc.
|
||||
PG_DB_NAME="myapp"
|
||||
PG_DB_USER="myapp"
|
||||
setup_postgresql_db
|
||||
```
|
||||
|
||||
### Node.js Setup
|
||||
|
||||
```bash
|
||||
NODE_VERSION="20"
|
||||
setup_nodejs
|
||||
npm install --no-save
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Only add app-specific dependencies**
|
||||
- Don't add: ca-certificates, curl, gnupg, wget, git, jq
|
||||
- These are handled by build.func
|
||||
|
||||
2. **Use tools.func helpers**
|
||||
- setup_nodejs, setup_python, setup_uv, setup_postgresql_db, setup_mysql_db, etc.
|
||||
|
||||
3. **Don't do version checks in install script**
|
||||
- Version checking happens in CT script's update_script()
|
||||
- Install script just installs the latest
|
||||
|
||||
4. **Structure:**
|
||||
- Dependencies
|
||||
- Runtime setup (tools.func)
|
||||
- Deployment (fetch from CT script)
|
||||
- Configuration files
|
||||
- Systemd service
|
||||
- Finalization
|
||||
|
||||
---
|
||||
|
||||
## Reference Scripts
|
||||
|
||||
See working examples:
|
||||
|
||||
- [Trip](https://github.com/community-scripts/ProxmoxVE/blob/main/install_scripts/trip-install.sh)
|
||||
- [Thingsboard](https://github.com/community-scripts/ProxmoxVE/blob/main/install_scripts/thingsboard-install.sh)
|
||||
- [UniFi](https://github.com/community-scripts/ProxmoxVE/blob/main/install_scripts/unifi-install.sh)
|
||||
|
||||
---
|
||||
|
||||
## Need Help?
|
||||
|
||||
- **[Modern Template](AppName-install.sh)** - Start here
|
||||
- **[CT Template](../templates_ct/AppName.sh)** - How CT scripts work
|
||||
- **[README.md](../README.md)** - Full contribution workflow
|
||||
- **[AI.md](../AI.md)** - AI-generated script guidelines
|
||||
|
||||
### 1.2 **Comments**
|
||||
|
||||
- Add clear comments for script metadata, including author, copyright, and license information.
|
||||
@@ -189,7 +330,7 @@ msg_ok "Installed Dependencies"
|
||||
### 6.2 **Verbosity**
|
||||
|
||||
- Use the appropiate flag (**-q** in the examples) for a command to suppres its output
|
||||
Example:
|
||||
Example:
|
||||
|
||||
```bash
|
||||
curl -fsSL
|
||||
|
||||
@@ -1,13 +1,137 @@
|
||||
# **AppName<span></span>.json Files**
|
||||
# JSON Metadata Files - Quick Reference
|
||||
|
||||
`AppName.json` files found in the `/json` directory. These files are used to provide informations for the website. For this guide we take `/json/snipeit.json` as example.
|
||||
The metadata file (`config/myapp.json`) tells the web interface how to display your application.
|
||||
|
||||
## Table of Contents
|
||||
---
|
||||
|
||||
- [**AppName.json Files**](#appnamejson-files)
|
||||
- [Table of Contents](#table-of-contents)
|
||||
- [1. JSON Generator](#1-json-generator)
|
||||
## Quick Start
|
||||
|
||||
## 1. JSON Generator
|
||||
**Use the JSON Generator Tool:**
|
||||
[https://community-scripts.github.io/ProxmoxVE/json-editor](https://community-scripts.github.io/ProxmoxVE/json-editor)
|
||||
|
||||
Use the [JSON Generator](https://community-scripts.github.io/ProxmoxVE/json-editor) to create this file for your application.
|
||||
1. Enter application details
|
||||
2. Generator creates `config/myapp.json`
|
||||
3. Copy the output to your contribution
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "MyApp",
|
||||
"slug": "myapp",
|
||||
"categories": ["utilities", "monitoring"],
|
||||
"date_created": "2025-01-15",
|
||||
"type": "ct",
|
||||
"interface_port": "3000",
|
||||
"logo": "https://example.com/logo.png",
|
||||
"config_path": "/etc/myapp/config.json",
|
||||
"description": "Brief description of what MyApp does",
|
||||
"install_methods": {
|
||||
"1": {
|
||||
"type": "ct",
|
||||
"resources": {
|
||||
"cpu": "2",
|
||||
"ram": "2048",
|
||||
"disk": "10"
|
||||
},
|
||||
"pre_install_msg": "Optional message shown before installation"
|
||||
}
|
||||
},
|
||||
"default_credentials": {
|
||||
"username": "admin",
|
||||
"password": "Generated during install"
|
||||
},
|
||||
"notes": "Optional setup notes",
|
||||
"notes_type": "markdown"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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 |
|
||||
|
||||
---
|
||||
|
||||
## Install Methods
|
||||
|
||||
Each installation method specifies resource requirements:
|
||||
|
||||
```json
|
||||
"install_methods": {
|
||||
"1": {
|
||||
"type": "ct",
|
||||
"resources": {
|
||||
"cpu": "2",
|
||||
"ram": "2048",
|
||||
"disk": "10"
|
||||
},
|
||||
"pre_install_msg": "Optional message"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Resource Defaults:**
|
||||
|
||||
- CPU: Cores (1-8)
|
||||
- RAM: Megabytes (256-4096)
|
||||
- Disk: Gigabytes (4-50)
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use the JSON Generator** - It validates structure
|
||||
2. **Keep descriptions short** - 100 characters max
|
||||
3. **Use real resource requirements** - Based on your testing
|
||||
4. **Include sensible defaults** - Pre-filled in install_methods
|
||||
5. **Slug must be lowercase** - No spaces, use hyphens
|
||||
|
||||
---
|
||||
|
||||
## Reference Examples
|
||||
|
||||
See actual examples in the repo:
|
||||
|
||||
- [config/trip.json](https://github.com/community-scripts/ProxmoxVE/blob/main/config/trip.json)
|
||||
- [config/thingsboard.json](https://github.com/community-scripts/ProxmoxVE/blob/main/config/thingsboard.json)
|
||||
- [config/unifi.json](https://github.com/community-scripts/ProxmoxVE/blob/main/config/unifi.json)
|
||||
|
||||
---
|
||||
|
||||
## Need Help?
|
||||
|
||||
- **[JSON Generator](https://community-scripts.github.io/ProxmoxVE/json-editor)** - Interactive tool
|
||||
- **[README.md](../README.md)** - Full contribution workflow
|
||||
- **[Quick Start](../README.md)** - Step-by-step guide
|
||||
|
||||
Reference in New Issue
Block a user