mirror of
https://github.com/community-scripts/ProxmoxVE.git
synced 2026-04-23 19:00:40 +00:00
cleanup: remove docs/, update README & CONTRIBUTING, fix repo config (#13770)
This commit is contained in:
CanbiZ (MickLesk)
committed by
GitHub
GitHub
parent
b2c0d7646e
commit
997e05dfb1
@@ -1,278 +0,0 @@
|
||||
# CT Container Scripts - Quick Reference
|
||||
|
||||
> [!WARNING]
|
||||
> **This is legacy documentation.** Refer to the **modern template** at [templates_ct/AppName.sh](AppName.sh) for best practices.
|
||||
>
|
||||
> 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
|
||||
|
||||
---
|
||||
|
||||
## Before Creating a Script
|
||||
|
||||
1. **Fork & Clone:**
|
||||
|
||||
```bash
|
||||
git clone https://github.com/YOUR_USERNAME/ProxmoxVE.git
|
||||
cd ProxmoxVE
|
||||
```
|
||||
|
||||
2. **Run setup-fork.sh** (updates all curl URLs to your fork):
|
||||
|
||||
```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
|
||||
#!/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="alpine"
|
||||
var_version="3.20"
|
||||
var_unprivileged="1"
|
||||
```
|
||||
|
||||
### Core Setup
|
||||
|
||||
```bash
|
||||
header_info "$APP"
|
||||
variables
|
||||
color
|
||||
catch_errors
|
||||
```
|
||||
|
||||
### Update Function
|
||||
|
||||
The modern template provides a standard update pattern:
|
||||
|
||||
```bash
|
||||
function update_script() {
|
||||
header_info
|
||||
check_container_storage
|
||||
check_container_resources
|
||||
|
||||
# Use tools.func helpers:
|
||||
check_for_gh_release "myapp" "owner/repo"
|
||||
fetch_and_deploy_gh_release "myapp" "owner/repo" "tarball" "latest" "/opt/myapp"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Patterns
|
||||
|
||||
### Check for Updates (App Repository)
|
||||
|
||||
Use `check_for_gh_release` with the **app repo**:
|
||||
|
||||
```bash
|
||||
check_for_gh_release "myapp" "owner/repo"
|
||||
```
|
||||
|
||||
### Deploy External App
|
||||
|
||||
Use `fetch_and_deploy_gh_release` with the **app repo**:
|
||||
|
||||
```bash
|
||||
fetch_and_deploy_gh_release "myapp" "owner/repo"
|
||||
```
|
||||
|
||||
### 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" "owner/repo"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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/MyApp-install.sh (2 files). Website metadata: use Report issue on the script's page on the website.
|
||||
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
|
||||
|
||||
````
|
||||
|
||||
### 3.4 **Verbosity**
|
||||
|
||||
- Use the appropriate flag (**-q** in the examples) for a command to suppress its output.
|
||||
Example:
|
||||
|
||||
```bash
|
||||
curl -fsSL
|
||||
unzip -q
|
||||
````
|
||||
|
||||
- If a command does not come with this functionality use `$STD` to suppress it's output.
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
$STD php artisan migrate --force
|
||||
$STD php artisan config:clear
|
||||
```
|
||||
|
||||
### 3.5 **Backups**
|
||||
|
||||
- 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
|
||||
|
||||
Example backup:
|
||||
|
||||
```bash
|
||||
mv /opt/snipe-it /opt/snipe-it-backup
|
||||
```
|
||||
|
||||
Example config restore:
|
||||
|
||||
```bash
|
||||
cp /opt/snipe-it-backup/.env /opt/snipe-it/.env
|
||||
cp -r /opt/snipe-it-backup/public/uploads/ /opt/snipe-it/public/uploads/
|
||||
cp -r /opt/snipe-it-backup/storage/private_uploads /opt/snipe-it/storage/private_uploads
|
||||
```
|
||||
|
||||
### 3.6 **Cleanup**
|
||||
|
||||
- Do not forget to remove any temporary files/folders such as zip-files or temporary backups.
|
||||
Example:
|
||||
|
||||
```bash
|
||||
rm -rf /opt/v${RELEASE}.zip
|
||||
rm -rf /opt/snipe-it-backup
|
||||
```
|
||||
|
||||
### 3.7 **No update function**
|
||||
|
||||
- In case you can not provide an update function use the following code to provide user feedback.
|
||||
|
||||
```bash
|
||||
function update_script() {
|
||||
header_info
|
||||
check_container_storage
|
||||
check_container_resources
|
||||
if [[ ! -d /opt/snipeit ]]; then
|
||||
msg_error "No ${APP} Installation Found!"
|
||||
exit
|
||||
fi
|
||||
msg_error "Currently we don't provide an update function for this ${APP}."
|
||||
exit
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4 **End of the script**
|
||||
|
||||
- `start`: Launches Whiptail dialogue
|
||||
- `build_container`: Collects and integrates user settings
|
||||
- `description`: Sets LXC container description
|
||||
- With `echo -e "${TAB}${GATEWAY}${BGN}http://${IP}${CL}"` you can point the user to the IP:PORT/folder needed to access the app.
|
||||
|
||||
```bash
|
||||
start
|
||||
build_container
|
||||
description
|
||||
|
||||
msg_ok "Completed successfully!\n"
|
||||
echo -e "${CREATING}${GN}${APP} setup has been successfully initialized!${CL}"
|
||||
echo -e "${INFO}${YW} Access it using the following URL:${CL}"
|
||||
echo -e "${TAB}${GATEWAY}${BGN}http://${IP}${CL}"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. **Contribution checklist**
|
||||
|
||||
- [ ] Shebang is correctly set (`#!/usr/bin/env bash`).
|
||||
- [ ] Correct link to _build.func_
|
||||
- [ ] Metadata (author, license) is included at the top.
|
||||
- [ ] Variables follow naming conventions.
|
||||
- [ ] Update function exists.
|
||||
- [ ] Update functions checks if app is installed and for new version.
|
||||
- [ ] Update function cleans up temporary files.
|
||||
- [ ] Script ends with a helpful message for the user to reach the application.
|
||||
@@ -1,138 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
source <(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/misc/build.func)
|
||||
# Copyright (c) 2021-2026 community-scripts ORG
|
||||
# Author: [YourGitHubUsername]
|
||||
# License: MIT | https://github.com/community-scripts/ProxmoxVE/raw/main/LICENSE
|
||||
# Source: [SOURCE_URL e.g. https://github.com/example/app]
|
||||
|
||||
# ============================================================================
|
||||
# APP CONFIGURATION
|
||||
# ============================================================================
|
||||
# These values are sent to build.func and define default container resources.
|
||||
# Users can customize these during installation via the interactive prompts.
|
||||
# ============================================================================
|
||||
|
||||
APP="[AppName]"
|
||||
var_tags="${var_tags:-[category1];[category2]}" # Max 2 tags, semicolon-separated
|
||||
var_cpu="${var_cpu:-2}" # CPU cores: 1-4 typical
|
||||
var_ram="${var_ram:-2048}" # RAM in MB: 512, 1024, 2048, etc.
|
||||
var_disk="${var_disk:-8}" # Disk in GB: 6, 8, 10, 20 typical
|
||||
var_os="${var_os:-debian}" # OS: debian, ubuntu, alpine
|
||||
var_version="${var_version:-13}" # OS Version: 13 (Debian), 24.04 (Ubuntu), 3.21 (Alpine)
|
||||
var_unprivileged="${var_unprivileged:-1}" # 1=unprivileged (secure), 0=privileged (for Docker/Podman)
|
||||
|
||||
# ============================================================================
|
||||
# INITIALIZATION - These are required in all CT scripts
|
||||
# ============================================================================
|
||||
header_info "$APP" # Display app name and setup header
|
||||
variables # Initialize build.func variables
|
||||
color # Load color variables for output
|
||||
catch_errors # Enable error handling with automatic exit on failure
|
||||
|
||||
# ============================================================================
|
||||
# UPDATE SCRIPT - Called when user selects "Update" from web interface
|
||||
# ============================================================================
|
||||
# This function is triggered by the web interface to update the application.
|
||||
# It should:
|
||||
# 1. Check if installation exists
|
||||
# 2. Check for new GitHub releases
|
||||
# 3. Stop running services
|
||||
# 4. Backup critical data
|
||||
# 5. Deploy new version
|
||||
# 6. Run post-update commands (migrations, config updates, etc.)
|
||||
# 7. Restore data if needed
|
||||
# 8. Start services
|
||||
#
|
||||
# Exit with `exit` at the end to prevent container restart.
|
||||
# ============================================================================
|
||||
|
||||
function update_script() {
|
||||
header_info
|
||||
check_container_storage
|
||||
check_container_resources
|
||||
|
||||
# Step 1: Verify installation exists
|
||||
if [[ ! -d /opt/[appname] ]]; then
|
||||
msg_error "No ${APP} Installation Found!"
|
||||
exit
|
||||
fi
|
||||
|
||||
# Step 2: Check if update is available
|
||||
if check_for_gh_release "[appname]" "YourUsername/YourRepo"; then
|
||||
|
||||
# Step 3: Stop services before update
|
||||
msg_info "Stopping Service"
|
||||
systemctl stop [appname]
|
||||
msg_ok "Stopped Service"
|
||||
|
||||
# Step 4: Backup critical data before overwriting
|
||||
msg_info "Backing up Data"
|
||||
cp -r /opt/[appname]/data /opt/[appname]_data_backup 2>/dev/null || true
|
||||
msg_ok "Backed up Data"
|
||||
|
||||
# Step 5: Download and deploy new version
|
||||
# CLEAN_INSTALL=1 removes old directory before extracting
|
||||
CLEAN_INSTALL=1 fetch_and_deploy_gh_release "[appname]" "owner/repo" "tarball" "latest" "/opt/[appname]"
|
||||
|
||||
# Step 6: Run post-update commands (uncomment as needed)
|
||||
# These examples show common patterns - use what applies to your app:
|
||||
#
|
||||
# For Node.js apps:
|
||||
# msg_info "Installing Dependencies"
|
||||
# cd /opt/[appname]
|
||||
# $STD npm ci --production
|
||||
# msg_ok "Installed Dependencies"
|
||||
#
|
||||
# For Python apps:
|
||||
# msg_info "Installing Dependencies"
|
||||
# cd /opt/[appname]
|
||||
# $STD uv sync --frozen
|
||||
# msg_ok "Installed Dependencies"
|
||||
#
|
||||
# For database migrations:
|
||||
# msg_info "Running Database Migrations"
|
||||
# cd /opt/[appname]
|
||||
# $STD npm run migrate
|
||||
# msg_ok "Ran Database Migrations"
|
||||
#
|
||||
# For PHP apps:
|
||||
# msg_info "Installing Dependencies"
|
||||
# cd /opt/[appname]
|
||||
# $STD composer install --no-dev
|
||||
# msg_ok "Installed Dependencies"
|
||||
|
||||
# Step 7: Restore data from backup
|
||||
msg_info "Restoring Data"
|
||||
cp -r /opt/[appname]_data_backup/. /opt/[appname]/data/ 2>/dev/null || true
|
||||
rm -rf /opt/[appname]_data_backup
|
||||
msg_ok "Restored Data"
|
||||
|
||||
# Step 8: Restart service with new version
|
||||
msg_info "Starting Service"
|
||||
systemctl start [appname]
|
||||
msg_ok "Started Service"
|
||||
msg_ok "Updated successfully!"
|
||||
fi
|
||||
exit
|
||||
}
|
||||
|
||||
# ============================================================================
|
||||
# MAIN EXECUTION - Container creation flow
|
||||
# ============================================================================
|
||||
# These are called by build.func and handle the full installation process:
|
||||
# 1. start - Initialize container creation
|
||||
# 2. build_container - Execute the install script inside container
|
||||
# 3. description - Display completion info and access details
|
||||
# ============================================================================
|
||||
|
||||
start
|
||||
build_container
|
||||
description
|
||||
|
||||
# ============================================================================
|
||||
# COMPLETION MESSAGE
|
||||
# ============================================================================
|
||||
msg_ok "Completed successfully!\n"
|
||||
echo -e "${CREATING}${GN}${APP} setup has been successfully initialized!${CL}"
|
||||
echo -e "${INFO}${YW} Access it using the following URL:${CL}"
|
||||
echo -e "${TAB}${GATEWAY}${BGN}http://${IP}:[PORT]${CL}"
|
||||
Reference in New Issue
Block a user