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 | | Function | Variable(s) | Example |
| -------------- | ----------------------------- | ---------------------------------------------------- | | -------------- | ----------------------------- | ---------------------------------------------------- |
| `setup_nodejs` | `NODE_VERSION`, `NODE_MODULE` | `NODE_VERSION="22" setup_nodejs` | | `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_go` | `GO_VERSION` | `GO_VERSION="1.22" setup_go` |
| `setup_rust` | `RUST_VERSION`, `RUST_CRATES` | `RUST_CRATES="monolith" setup_rust` | | `setup_rust` | `RUST_VERSION`, `RUST_CRATES` | `RUST_CRATES="monolith" setup_rust` |
| `setup_ruby` | `RUBY_VERSION` | `RUBY_VERSION="3.3" setup_ruby` | | `setup_ruby` | `RUBY_VERSION` | `RUBY_VERSION="3.3" setup_ruby` |
@@ -465,7 +465,7 @@ EOF
msg_ok "Saved Credentials" msg_ok "Saved Credentials"
# ✅ CORRECT - credentials are stored in .env or shown in final message only # ✅ 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 ### 15. Wrong Footer Pattern

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

@@ -1,14 +1,41 @@
<div align="center"> # 🧪 Code Audit: LXC Script Flow
<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>
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.) This guide explains the current execution flow and what to verify during reviews.
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.
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 ### 4. Run setup-fork.sh to auto-configure your fork
```bash ```bash
bash docs/contribution/setup-fork.sh bash docs/contribution/setup-fork.sh --full
``` ```
This script automatically: 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 cd ProxmoxVE
# Run setup script (auto-detects your username from git) # Run setup script (auto-detects your username from git)
bash setup-fork.sh bash docs/contribution/setup-fork.sh --full
``` ```
That's it! ✅ That's it! ✅
@@ -67,7 +67,7 @@ source <(curl -fsSL https://raw.githubusercontent.com/john/ProxmoxVE/main/misc/b
### Auto-Detect (Recommended) ### Auto-Detect (Recommended)
```bash ```bash
bash setup-fork.sh bash docs/contribution/setup-fork.sh --full
``` ```
Automatically reads your GitHub username from `git remote origin url` 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 ### Specify Username
```bash ```bash
bash setup-fork.sh john bash docs/contribution/setup-fork.sh --full john
``` ```
Updates links to `github.com/john/ProxmoxVE` Updates links to `github.com/john/ProxmoxVE`
@@ -83,7 +83,7 @@ Updates links to `github.com/john/ProxmoxVE`
### Custom Repository Name ### Custom Repository Name
```bash ```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` Updates links to `github.com/john/my-fork`
@@ -92,19 +92,12 @@ Updates links to `github.com/john/my-fork`
## What Gets Updated? ## 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) - `ct/`, `install/`, `vm/` scripts
- `docs/README.md` (1 link) - `misc/` function libraries
- `docs/INDEX.md` (3 links) - `docs/` (including `docs/contribution/`)
- `docs/EXIT_CODES.md` (2 links) - Code examples in documentation
- `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
--- ---
@@ -132,7 +125,7 @@ The script updates these documentation files:
4. **Follow the guide** 4. **Follow the guide**
```bash ```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 # Make sure you cloned the repo first
git clone https://github.com/YOUR_USERNAME/ProxmoxVE.git git clone https://github.com/YOUR_USERNAME/ProxmoxVE.git
cd ProxmoxVE cd ProxmoxVE
bash setup-fork.sh bash docs/contribution/setup-fork.sh --full
``` ```
### "Could not auto-detect GitHub username" ### "Could not auto-detect GitHub username"
@@ -191,15 +184,15 @@ git remote -v
# Fix it: # Fix it:
git remote set-url origin https://github.com/YOUR_USERNAME/ProxmoxVE.git 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" ### "Permission denied"
```bash ```bash
# Make script executable # Make script executable
chmod +x setup-fork.sh chmod +x docs/contribution/setup-fork.sh
bash setup-fork.sh bash docs/contribution/setup-fork.sh --full
``` ```
### Reverted Changes by Accident? ### Reverted Changes by Accident?
@@ -208,14 +201,15 @@ bash setup-fork.sh
# Backups are created automatically # Backups are created automatically
git checkout docs/*.backup git checkout docs/*.backup
# Or just re-run setup-fork.sh # Or just re-run setup-fork.sh
bash docs/contribution/setup-fork.sh --full
``` ```
--- ---
## Next Steps ## Next Steps
1. ✅ Run `bash setup-fork.sh` 1. ✅ Run `bash docs/contribution/setup-fork.sh --full`
2. 📖 Read [docs/CONTRIBUTION_GUIDE.md](docs/CONTRIBUTION_GUIDE.md) 2. 📖 Read [docs/contribution/GUIDE.md](GUIDE.md)
3. 🍴 Choose your contribution path: 3. 🍴 Choose your contribution path:
- **Containers** → [docs/ct/README.md](docs/ct/README.md) - **Containers** → [docs/ct/README.md](docs/ct/README.md)
- **Installation** → [docs/install/README.md](docs/install/README.md) - **Installation** → [docs/install/README.md](docs/install/README.md)
@@ -228,10 +222,10 @@ git checkout docs/*.backup
## Questions? ## Questions?
- **Fork Setup Issues?** → See [Troubleshooting](#troubleshooting) above - **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` - **Git Workflows?** → `cat .git-setup-info`
- **Project Structure?** → [docs/README.md](docs/README.md) - **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 cd ProxmoxVE
# 3. Run fork setup script (automatically configures everything) # 3. Run fork setup script (automatically configures everything)
bash setup-fork.sh bash docs/contribution/setup-fork.sh --full
# This auto-detects your username and updates all documentation links # --full updates ct/, install/, vm/, docs/, misc/ links for fork testing
# 4. Read the git workflow tips # 4. Read the git workflow tips
cat .git-setup-info cat .git-setup-info
@@ -113,9 +113,9 @@ ProxmoxVE/
│ └── alpine-tools.func # Alpine tools │ └── alpine-tools.func # Alpine tools
│ │
├── docs/ # 📚 Documentation ├── docs/ # 📚 Documentation
│ ├── UPDATED_APP-ct.md # Container script guide │ ├── ct/DETAILED_GUIDE.md # Container script guide
│ ├── UPDATED_APP-install.md # Install script guide │ ├── install/DETAILED_GUIDE.md # Install script guide
│ └── CONTRIBUTING.md # (This file!) │ └── contribution/README.md # Contribution overview
│ │
├── tools/ # 🔧 Proxmox management tools ├── tools/ # 🔧 Proxmox management tools
│ └── pve/ │ └── pve/
@@ -201,27 +201,18 @@ git rebase upstream/main
git push origin feat/add-myapp 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 # 1. SSH into Proxmox host
ssh root@192.168.1.100 ssh root@192.168.1.100
# 2. Download your script # 2. Test via curl from your fork (CT script only)
curl -O https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/feat/myapp/ct/myapp.sh 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 > **Note:** Do not edit URLs manually or run install scripts directly. The CT script calls the install script inside the container.
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!
````
#### Option C: Using Curl (Recommended for Real Testing) #### 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 # This tests the actual GitHub URLs, not local files
``` ```
#### Option D: Docker Testing (Without Proxmox) #### Option D: Static Checks (Without Proxmox)
```bash ```bash
# You can test script syntax/functionality locally (limited) # You can validate syntax and linting locally (limited)
# Note: Won't fully test (no Proxmox, no actual container) # Note: This does NOT replace real Proxmox testing
# Run ShellCheck # Run ShellCheck
shellcheck ct/myapp.sh shellcheck ct/myapp.sh
@@ -260,12 +251,9 @@ cp ct/example.sh ct/myapp.sh
cp install/example-install.sh install/myapp-install.sh cp install/example-install.sh install/myapp-install.sh
``` ```
**For Database Apps** (PostgreSQL, MongoDB): **For Database Apps** (PostgreSQL, MariaDB, MongoDB):
```bash Use the standard templates and the database helpers from `tools.func` (no Docker).
cp ct/docker.sh ct/myapp.sh # Use Docker container
# OR manual setup for more control
```
**For Alpine Linux Apps** (lightweight): **For Alpine Linux Apps** (lightweight):
@@ -280,7 +268,7 @@ cp ct/docker.sh ct/myapp.sh # Use Docker container
```bash ```bash
#!/usr/bin/env 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: # Update these:
APP="MyAwesomeApp" # Display name APP="MyAwesomeApp" # Display name
@@ -307,17 +295,19 @@ function update_script() {
exit exit
fi fi
# Get latest version if check_for_gh_release "myapp" "owner/repo"; then
RELEASE=$(curl -fsSL https://api.github.com/repos/user/repo/releases/latest | \ msg_info "Stopping Service"
grep "tag_name" | awk '{print substr($2, 2, length($2)-3)}') systemctl stop myapp
msg_ok "Stopped Service"
if [[ ! -f /opt/${APP}_version.txt ]] || [[ "${RELEASE}" != "$(cat /opt/${APP}_version.txt)" ]]; then CLEAN_INSTALL=1 fetch_and_deploy_gh_release "myapp" "owner/repo" "tarball" "latest" "/opt/myapp"
msg_info "Updating ${APP} to v${RELEASE}"
# ... update logic ... # ... update logic (migrations, rebuilds, etc.) ...
echo "${RELEASE}" > /opt/${APP}_version.txt
msg_ok "Updated ${APP}" msg_info "Starting Service"
else systemctl start myapp
msg_ok "No update required. ${APP} is already at v${RELEASE}." msg_ok "Started Service"
msg_ok "Updated successfully!"
fi fi
exit exit
} }
@@ -362,24 +352,12 @@ update_os
msg_info "Installing Dependencies" msg_info "Installing Dependencies"
$STD apt-get install -y \ $STD apt-get install -y \
curl \
wget \
git \
build-essential build-essential
msg_ok "Installed Dependencies" msg_ok "Installed Dependencies"
msg_info "Setting up Node.js"
NODE_VERSION="22" setup_nodejs NODE_VERSION="22" setup_nodejs
msg_ok "Node.js installed"
msg_info "Downloading Application" fetch_and_deploy_gh_release "myapp" "owner/repo" "tarball" "latest" "/opt/myapp"
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
motd_ssh motd_ssh
customize customize
@@ -674,27 +652,19 @@ shellcheck install/myapp-install.sh
# 1. SSH into Proxmox host # 1. SSH into Proxmox host
ssh root@YOUR_PROXMOX_IP ssh root@YOUR_PROXMOX_IP
# 2. Download your script # 2. Test via curl from your fork (CT script only)
curl -O https://raw.githubusercontent.com/YOUR_USER/ProxmoxVE/feat/myapp/ct/myapp.sh 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 # 3. Test interaction:
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:
# - Select installation mode # - Select installation mode
# - Confirm settings # - Confirm settings
# - Monitor installation # - Monitor installation
# 7. Verify container created # 4. Verify container created
pct list | grep myapp pct list | grep myapp
# 8. Log into container and verify app # 5. Log into container and verify app
pct exec 100 bash 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. > ⚠️ **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 ### Node.js + PostgreSQL
**Koel** - Music streaming with PHP + Node.js + PostgreSQL **Koel** - Music streaming with PHP + Node.js + PostgreSQL
| File | Link | | File | Link |
| ----------------- | -------------------------------------------------------- | | ----------------- | -------------------------------------------------------- |
| CT (update logic) | [ct/koel.sh](../../ct/koel.sh) | | CT (update logic) | [ct/koel.sh](../../ct/koel.sh) |
| Install | [install/koel-install.sh](../../install/koel-install.sh) | | Install | [install/koel-install.sh](../../install/koel-install.sh) |
**Actual Budget** - Finance app with npm global install **Actual Budget** - Finance app with npm global install
| File | Link | | File | Link |
| ----------------- | ------------------------------------------------------------------------ | | ----------------- | ------------------------------------------------------------------------ |
| CT (update logic) | [ct/actualbudget.sh](../../ct/actualbudget.sh) | | CT (update logic) | [ct/actualbudget.sh](../../ct/actualbudget.sh) |
| Install | [install/actualbudget-install.sh](../../install/actualbudget-install.sh) | | Install | [install/actualbudget-install.sh](../../install/actualbudget-install.sh) |
### Python + uv ### Python + uv
**MeTube** - YouTube downloader with Python uv + Node.js + Deno **MeTube** - YouTube downloader with Python uv + Node.js + Deno
| File | Link | | File | Link |
| ----------------- | ------------------------------------------------------------ | | ----------------- | ------------------------------------------------------------ |
| CT (update logic) | [ct/metube.sh](../../ct/metube.sh) | | CT (update logic) | [ct/metube.sh](../../ct/metube.sh) |
| Install | [install/metube-install.sh](../../install/metube-install.sh) | | Install | [install/metube-install.sh](../../install/metube-install.sh) |
**Endurain** - Fitness tracker with Python uv + PostgreSQL/PostGIS **Endurain** - Fitness tracker with Python uv + PostgreSQL/PostGIS
| File | Link | | File | Link |
| ----------------- | ---------------------------------------------------------------- | | ----------------- | ---------------------------------------------------------------- |
| CT (update logic) | [ct/endurain.sh](../../ct/endurain.sh) | | CT (update logic) | [ct/endurain.sh](../../ct/endurain.sh) |
| Install | [install/endurain-install.sh](../../install/endurain-install.sh) | | Install | [install/endurain-install.sh](../../install/endurain-install.sh) |
### PHP + MariaDB/MySQL ### PHP + MariaDB/MySQL
**Wallabag** - Read-it-later with PHP + MariaDB + Redis + Nginx **Wallabag** - Read-it-later with PHP + MariaDB + Redis + Nginx
| File | Link | | File | Link |
| ----------------- | ---------------------------------------------------------------- | | ----------------- | ---------------------------------------------------------------- |
| CT (update logic) | [ct/wallabag.sh](../../ct/wallabag.sh) | | CT (update logic) | [ct/wallabag.sh](../../ct/wallabag.sh) |
| Install | [install/wallabag-install.sh](../../install/wallabag-install.sh) | | Install | [install/wallabag-install.sh](../../install/wallabag-install.sh) |
**InvoiceNinja** - Invoicing with PHP + MariaDB + Supervisor **InvoiceNinja** - Invoicing with PHP + MariaDB + Supervisor
| File | Link | | File | Link |
| ----------------- | ------------------------------------------------------------------------ | | ----------------- | ------------------------------------------------------------------------ |
| CT (update logic) | [ct/invoiceninja.sh](../../ct/invoiceninja.sh) | | CT (update logic) | [ct/invoiceninja.sh](../../ct/invoiceninja.sh) |
| Install | [install/invoiceninja-install.sh](../../install/invoiceninja-install.sh) | | Install | [install/invoiceninja-install.sh](../../install/invoiceninja-install.sh) |
**BookStack** - Wiki/Docs with PHP + MariaDB + Apache **BookStack** - Wiki/Docs with PHP + MariaDB + Apache
| File | Link | | File | Link |
| ----------------- | ------------------------------------------------------------------ | | ----------------- | ------------------------------------------------------------------ |
| CT (update logic) | [ct/bookstack.sh](../../ct/bookstack.sh) | | CT (update logic) | [ct/bookstack.sh](../../ct/bookstack.sh) |
| Install | [install/bookstack-install.sh](../../install/bookstack-install.sh) | | Install | [install/bookstack-install.sh](../../install/bookstack-install.sh) |
### PHP + SQLite (Simple) ### PHP + SQLite (Simple)
**Speedtest Tracker** - Speedtest with PHP + SQLite + Nginx **Speedtest Tracker** - Speedtest with PHP + SQLite + Nginx
| File | Link | | File | Link |
| ----------------- | ---------------------------------------------------------------------------------- | | ----------------- | ---------------------------------------------------------------------------------- |
| CT (update logic) | [ct/speedtest-tracker.sh](../../ct/speedtest-tracker.sh) | | CT (update logic) | [ct/speedtest-tracker.sh](../../ct/speedtest-tracker.sh) |
| Install | [install/speedtest-tracker-install.sh](../../install/speedtest-tracker-install.sh) | | Install | [install/speedtest-tracker-install.sh](../../install/speedtest-tracker-install.sh) |
--- ---
@@ -95,7 +97,7 @@
Install Node.js from NodeSource repository. Install Node.js from NodeSource repository.
```bash ```bash
# Default (Node.js 22) # Default (Node.js 24)
setup_nodejs setup_nodejs
# Specific version # Specific version
@@ -135,8 +137,12 @@ $STD cargo build --release
Install Python uv package manager (fast pip/venv replacement). Install Python uv package manager (fast pip/venv replacement).
```bash ```bash
# Default
setup_uv setup_uv
# Install a specific Python version
PYTHON_VERSION="3.12" setup_uv
# Use in script # Use in script
setup_uv setup_uv
cd /opt/myapp cd /opt/myapp
@@ -160,7 +166,7 @@ Install PHP with configurable modules and FPM/Apache support.
setup_php setup_php
# Full configuration # Full configuration
PHP_VERSION="8.3" \ PHP_VERSION="8.4" \
PHP_MODULE="mysqli,gd,curl,mbstring,xml,zip,ldap" \ PHP_MODULE="mysqli,gd,curl,mbstring,xml,zip,ldap" \
PHP_FPM="YES" \ PHP_FPM="YES" \
PHP_APACHE="YES" \ PHP_APACHE="YES" \
@@ -168,12 +174,12 @@ setup_php
``` ```
**Environment Variables:** **Environment Variables:**
| Variable | Default | Description | | Variable | Default | Description |
| ------------- | ------- | ------------------------------- | | ------------- | ------- | ------------------------------- |
| `PHP_VERSION` | `8.3` | PHP version to install | | `PHP_VERSION` | `8.4` | PHP version to install |
| `PHP_MODULE` | `""` | Comma-separated list of modules | | `PHP_MODULE` | `""` | Comma-separated list of modules |
| `PHP_FPM` | `NO` | Install PHP-FPM | | `PHP_FPM` | `NO` | Install PHP-FPM |
| `PHP_APACHE` | `NO` | Install Apache module | | `PHP_APACHE` | `NO` | Install Apache module |
### `setup_composer` ### `setup_composer`
@@ -239,12 +245,12 @@ setup_mysql
Install PostgreSQL server. Install PostgreSQL server.
```bash ```bash
# Default (PostgreSQL 17) # Default (PostgreSQL 16)
setup_postgresql setup_postgresql
# Specific version # Specific version
PG_VERSION="16" setup_postgresql PG_VERSION="16" setup_postgresql
PG_VERSION="17" setup_postgresql PG_VERSION="16" setup_postgresql
``` ```
### `setup_postgresql_db` ### `setup_postgresql_db`
@@ -302,17 +308,17 @@ CLEAN_INSTALL=1 fetch_and_deploy_gh_release "appname" "owner/repo" "tarball" "la
``` ```
**Parameters:** **Parameters:**
| Parameter | Default | Description | | Parameter | Default | Description |
| --------------- | ------------- | ----------------------------------------------------------------- | | --------------- | ------------- | ----------------------------------------------------------------- |
| `name` | required | App name (for version tracking) | | `name` | required | App name (for version tracking) |
| `repo` | required | GitHub repo (`owner/repo`) | | `repo` | required | GitHub repo (`owner/repo`) |
| `type` | `tarball` | Release type: `tarball`, `zipball`, `prebuild`, `binary` | | `type` | `tarball` | Release type: `tarball`, `zipball`, `prebuild`, `binary` |
| `version` | `latest` | Version tag or `latest` | | `version` | `latest` | Version tag or `latest` |
| `dest` | `/opt/[name]` | Destination directory | | `dest` | `/opt/[name]` | Destination directory |
| `asset_pattern` | `""` | For `prebuild`: glob pattern to match asset (e.g. `app-*.tar.gz`) | | `asset_pattern` | `""` | For `prebuild`: glob pattern to match asset (e.g. `app-*.tar.gz`) |
**Environment Variables:** **Environment Variables:**
| Variable | Description | | Variable | Description |
| ----------------- | ------------------------------------------------------------ | | ----------------- | ------------------------------------------------------------ |
| `CLEAN_INSTALL=1` | Remove destination directory before extracting (for updates) | | `CLEAN_INSTALL=1` | Remove destination directory before extracting (for updates) |
@@ -526,7 +532,7 @@ msg_ok "Installed Dependencies"
# Setup runtimes and databases FIRST # Setup runtimes and databases FIRST
NODE_VERSION="22" setup_nodejs 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 PG_DB_NAME="myapp" PG_DB_USER="myapp" setup_postgresql_db
import_local_ip 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 cd ProxmoxVE
# 3. Auto-configure your fork (IMPORTANT - updates all links!) # 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 # 4. Create a feature branch
git checkout -b feature/my-awesome-app 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 cp docs/contribution/templates_json/AppName.json frontend/public/json/myapp.json
# Edit metadata: name, slug, categories, description, resources, etc. # Edit metadata: name, slug, categories, description, resources, etc.
# 9. Test the install script (if you created one) # 9. No direct install-script test
bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/install/myapp-install.sh)" # Install scripts are executed by the CT script inside the container
# ⏱️ GitHub may take 10-30 seconds to update files - be patient!
# 10. Commit ONLY your new files (see Cherry-Pick section below!) # 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 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) # ✅ Users run from GitHub (normal usage after PR merged)
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/myapp.sh)" bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/myapp.sh)"
# For installation on existing Proxmox hosts # Install scripts are called by the CT script and are not run directly by users
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/install/myapp-install.sh)"
``` ```
### Development vs. Production Execution ### 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: When you clone your fork, run the setup script to automatically configure everything:
```bash ```bash
bash docs/contribution/setup-fork.sh bash docs/contribution/setup-fork.sh --full
``` ```
**What it does:** **What it does:**
- Auto-detects your GitHub username from git config - Auto-detects your GitHub username from git config
- Auto-detects your fork repository name - 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 - Creates `.git-setup-info` with your configuration
- Allows you to develop and test independently in your fork - 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 - **[HELPER_FUNCTIONS.md](HELPER_FUNCTIONS.md)** - Reference for all tools.func helper functions
- **Container Scripts** - `/ct/` templates and guidelines - **Container Scripts** - `/ct/` templates and guidelines
- **Install Scripts** - `/install/` 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 ### Quick Checklist
@@ -581,7 +579,7 @@ Two ways:
**Option 1: Run setup script again** **Option 1: Run setup script again**
```bash ```bash
bash docs/contribution/setup-fork.sh bash docs/contribution/setup-fork.sh --full
``` ```
**Option 2: Manual sync** **Option 2: Manual sync**
@@ -633,7 +631,7 @@ See "Using AI Assistants" section above for:
## 🚀 Ready to Contribute? ## 🚀 Ready to Contribute?
1. **Fork** the repository 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.) 3. **Choose** your contribution type (container, installation, tools, etc.)
4. **Read** the appropriate detailed guide 4. **Read** the appropriate detailed guide
5. **Create** your feature branch 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 EOF
print_success "Created .git-setup-info file" 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 " 1. Review the changes: git diff"
echo " 2. Check .git-setup-info for recommended git workflow" echo " 2. Check .git-setup-info for recommended git workflow"
echo " 3. Start developing: git checkout -b feature/my-app" 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 "" echo ""
print_success "Happy contributing! 🚀" print_success "Happy contributing! 🚀"

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

@@ -102,8 +102,8 @@ function update_script() {
check_container_resources check_container_resources
# Use tools.func helpers: # Use tools.func helpers:
check_for_gh_release "myapp" "YourUsername/ProxmoxVE" check_for_gh_release "myapp" "owner/repo"
fetch_and_deploy_gh_release "myapp" "app/owner" "appname.tar.gz" "latest" "/opt/myapp" fetch_and_deploy_gh_release "myapp" "owner/repo" "tarball" "latest" "/opt/myapp"
} }
``` ```
@@ -111,20 +111,20 @@ function update_script() {
## Key Patterns ## 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 ```bash
check_for_gh_release "myapp" "YourUsername/ProxmoxVE" check_for_gh_release "myapp" "owner/repo"
``` ```
### Deploy External App ### Deploy External App
Use `fetch_and_deploy_gh_release` with **target app repo**: Use `fetch_and_deploy_gh_release` with the **app repo**:
```bash ```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 ### Avoid Manual Version Checking
@@ -138,7 +138,7 @@ RELEASE=$(curl -fsSL https://api.github.com/repos/myapp/myapp/releases/latest |
✅ NEW (use tools.func): ✅ NEW (use tools.func):
```bash ```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 - **[AI.md](../AI.md)** - AI-generated script guidelines
- **[FORK_SETUP.md](../FORK_SETUP.md)** - Why setup-fork.sh is important - **[FORK_SETUP.md](../FORK_SETUP.md)** - Why setup-fork.sh is important
- **[Slack Community](https://discord.gg/your-link)** - Ask questions - **[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: > 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 > - Automatic dependency installation via build.func
> - Standardized environment variable patterns > - 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", "name": "MyApp",
"slug": "myapp", "slug": "myapp",
"categories": ["utilities", "monitoring"], "categories": [1],
"date_created": "2025-01-15", "date_created": "2026-01-18",
"type": "ct", "type": "ct",
"interface_port": "3000", "updateable": true,
"logo": "https://example.com/logo.png", "privileged": false,
"config_path": "/etc/myapp/config.json", "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", "description": "Brief description of what MyApp does",
"install_methods": { "install_methods": [
"1": { {
"type": "ct", "type": "default",
"script": "ct/myapp.sh",
"resources": { "resources": {
"cpu": "2", "cpu": 2,
"ram": "2048", "ram": 2048,
"disk": "10" "hdd": 8,
}, "os": "Debian",
"pre_install_msg": "Optional message shown before installation" "version": "13"
}
} }
}, ],
"default_credentials": { "default_credentials": {
"username": "admin", "username": null,
"password": "Generated during install" "password": null
}, },
"notes": "Optional setup notes", "notes": [
"notes_type": "markdown" {
"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 Reference
| Field | Required | Example | Notes | | Field | Required | Example | Notes |
| --------------------- | -------- | ------------------------ | ---------------------------------------------- | | --------------------- | -------- | ----------------- | ---------------------------------------------- |
| `name` | Yes | "MyApp" | Display name | | `name` | Yes | "MyApp" | Display name |
| `slug` | Yes | "myapp" | URL-friendly identifier (lowercase, no spaces) | | `slug` | Yes | "myapp" | URL-friendly identifier (lowercase, no spaces) |
| `categories` | Yes | ["utilities"] | One or more from available list | | `categories` | Yes | [1] | One or more category IDs |
| `date_created` | Yes | "2025-01-15" | Format: YYYY-MM-DD | | `date_created` | Yes | "2026-01-18" | Format: YYYY-MM-DD |
| `type` | Yes | "ct" | Container type: "ct" or "vm" | | `type` | Yes | "ct" | Container type: "ct" or "vm" |
| `interface_port` | Yes | "3000" | Default web interface port | | `interface_port` | Yes | 3000 | Default web interface port |
| `logo` | No | "https://..." | Logo URL (64px x 64px PNG) | | `logo` | No | "https://..." | Logo URL (64px x 64px PNG) |
| `config_path` | Yes | "/etc/myapp/config.json" | Main config file location | | `config_path` | Yes | "/opt/myapp/.env" | Main config file location |
| `description` | Yes | "App description" | Brief description (100 chars) | | `description` | Yes | "App description" | Brief description (100 chars) |
| `install_methods` | Yes | See below | Installation resources | | `install_methods` | Yes | See below | Installation resources (array) |
| `default_credentials` | No | See below | Optional default login | | `default_credentials` | No | See below | Optional default login |
| `notes` | No | "Setup info" | Additional notes | | `notes` | No | See below | Additional notes (array) |
| `notes_type` | No | "markdown" | Format of notes field |
--- ---
@@ -75,17 +84,19 @@ The metadata file (`frontend/public/json/myapp.json`) tells the web interface ho
Each installation method specifies resource requirements: Each installation method specifies resource requirements:
```json ```json
"install_methods": { "install_methods": [
"1": { {
"type": "ct", "type": "default",
"script": "ct/myapp.sh",
"resources": { "resources": {
"cpu": "2", "cpu": 2,
"ram": "2048", "ram": 2048,
"disk": "10" "hdd": 8,
}, "os": "Debian",
"pre_install_msg": "Optional message" "version": "13"
}
} }
} ]
``` ```
**Resource Defaults:** **Resource Defaults:**
@@ -98,15 +109,32 @@ Each installation method specifies resource requirements:
## Common Categories ## Common Categories
- `utilities` - Tools and utilities - `0` Miscellaneous
- `monitoring` - Monitoring/logging - `1` Proxmox & Virtualization
- `media` - Media servers - `2` Operating Systems
- `databases` - Database systems - `3` Containers & Docker
- `communication` - Chat/messaging - `4` Network & Firewall
- `smart-home` - Home automation - `5` Adblock & DNS
- `development` - Dev tools - `6` Authentication & Security
- `security` - Security tools - `7` Backup & Recovery
- `storage` - File storage - `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
--- ---