Proxmox/ProxmoxVE
1
0
Fork 1
mirror of https://github.com/community-scripts/ProxmoxVE.git synced 2026-02-03 20:03:25 +01:00
Code Issues Packages Projects Releases Wiki Activity

Update contribution docs for fork setup and metadata

Browse Source 
Revised documentation to standardize use of 'bash docs/contribution/setup-fork.sh --full' for fork configuration, clarified install script execution flow, and updated JSON metadata template and field references. Improved helper function docs, resource requirements, and category lists. Updated references and instructions throughout for consistency and accuracy.
This commit is contained in:
CanbiZ
2026-01-18 18:56:21 +01:00
parent 959bbb3a26
commit b87fddbf6a
11 changed files with 244 additions and 225 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/contribution/AI.md
View File

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

49
docs/contribution/CODE-AUDIT.md
View File

@@ -1,14 +1,41 @@
<div align="center">
<img src="https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/misc/images/logo.png" height="100px" />
</div>
<h2><div align="center">Exploring the Scripts and Steps Involved in an Application LXC Installation</div></h2>
# 🧪 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/<appname>.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`

2
docs/contribution/CONTRIBUTING.md
View File

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

44
docs/contribution/FORK_SETUP.md
View File

@@ -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! 🚀

104
docs/contribution/GUIDE.md
View File

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

90
docs/contribution/HELPER_FUNCTIONS.md
View File

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

20
docs/contribution/README.md
View File

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

4
docs/contribution/setup-fork.sh
View File

@@ -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! 🚀"

20
docs/contribution/templates_ct/AppName.md
View File

@@ -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
}
````

2
docs/contribution/templates_install/AppName-install.md
View File

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

130
docs/contribution/templates_json/AppName.md
View File

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