mirror of
https://github.com/community-scripts/ProxmoxVE.git
synced 2026-04-18 16:32:17 +00:00
github: extend docs / contribution / templates (#10921)
* Enhance setup-fork.sh with --full mode and misc/ targeting Added a new --full flag to setup-fork.sh to allow updating all files, not just those in misc/. Updated documentation and usage examples to clarify the new behavior. Improved file search and replacement logic for broader compatibility and flexibility. * add AI.md * fix links in AI.md * Update contribution docs and templates for best practices Refreshed AI.md with new reference scripts, expanded checklist, and improved AI assistant tips. Updated container and install script templates for modern defaults (Debian 13, larger disk, two tags), clarified helper function usage, and improved update/backup patterns. Enhanced JSON template with realistic metadata, new fields, and example notes. * Update fetch_and_deploy_gh_release usage in docs and templates Standardize the usage of fetch_and_deploy_gh_release by specifying all arguments, including mode, version, and target directory, in AI.md and template scripts. This clarifies the function's usage and ensures consistency across documentation and install/update templates. * Revise contribution docs and update CT template Expanded and clarified contribution documentation for forking, local development, cherry-picking, and AI-assisted code generation. Improved explanations for setup-fork.sh, local testing, and PR submission. Enhanced the container script template with detailed comments, clearer update_script structure, and step-by-step guidance for maintainers and contributors. * Update fork and release instructions in contribution docs Replaced placeholder GitHub repo references with 'YourUsername/YourRepo' throughout documentation for clarity. Expanded explanations in FORK_SETUP.md and README.md to clarify the difference between development and production script execution, and emphasized the importance of cherry-picking only relevant files for PRs. Updated install script template examples to use the new repo placeholder. * Update GitHub repo placeholders in docs and templates Replaced 'YourUsername/YourRepo' with 'owner/repo' in documentation and template scripts for consistency and clarity. This change standardizes example usage and reduces confusion for contributors. * Move user submitted guides to guides directory Renamed USER_SUBMITTED_GUIDES.md from docs/contribution to docs/guides for improved documentation organization. * 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. * Update contribution docs for new file structure Updated documentation to reflect the migration of install scripts from install_scripts/ to install/, and JSON metadata from config/ to frontend/public/json/. Adjusted all relevant paths, instructions, and examples to match the new directory structure for improved clarity and consistency. * Update contribution docs for fork setup and metadata 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. * Docs: add GPU/TUN, update endpoints & tool refs Documentation updates across guides and function references: - Added var_gpu and var_tun configuration entries to CONFIGURATION_REFERENCE (GPU passthrough and TUN/TAP support), including features and prerequisites. - Fixed repository URLs throughout UNATTENDED_DEPLOYMENTS and examples: replaced community-scripts/ProxmoxVED with community-scripts/ProxmoxVE and updated curl usage to the new paths. - Added an "Advanced Configuration Variables" table and examples (var_os, var_version, var_gpu, var_tun, var_nesting) to UNATTENDED_DEPLOYMENTS; adjusted sample apps, hostnames, and container mappings in batch examples. - Switched API endpoints in API_FUNCTIONS_REFERENCE and API_USAGE_EXAMPLES from http://api.community-scripts.org to https://api.community-scripts.org. - Expanded BUILD_FUNC_FUNCTIONS_REFERENCE with container resource/ID management helper descriptions (validate_container_id, get_valid_container_id, maxkeys_check, get_current_ip, update_motd_ip). - Large edits to TOOLS_FUNC_FUNCTIONS_REFERENCE: renamed/refactored helper signatures and docs (pkg_install -> install_packages_with_retry, pkg_update -> upgrade_packages_with_retry), added new tooling functions (fetch_and_deploy_gh_release, check_for_gh_release, prepare_repository_setup, verify_tool_version) and updated examples and feature notes. - Updated vm/README.md to list additional VM scripts (new and reorganized examples). These are documentation-only changes to clarify configuration options, correct links and endpoints, and expand the reference material for tooling and build helpers. * Docs: expand developer/debugging and tools references Add extensive documentation and examples across contribution, guides, templates and tools references. Key changes: - Introduce a Developer Mode & Debugging section (dev_mode flags: trace, keep, pause, breakpoint, logs, dryrun, motd) in CONTRIBUTING.md with usage example. - Provide a standard update_script() pattern and BookStack example in GUIDE.md to clarify update flow (stop services, backup, deploy, restore, migrate, restart). - Add new helper entries (BookLore, KaraKeep) and advanced repository helpers (setup_deb822_repo, prepare_repository_setup, cleanup_tool_keyrings) plus utilities (setup_meilisearch, verify_tool_version) in HELPER_FUNCTIONS.md. - Update install template to suggest PNPM, Java 21 and Meilisearch; update example DB setup notes in AppName-install.sh. - Add var_diagnostics option and switch var_fuse to boolean/toggle wording in CONFIGURATION_REFERENCE.md; clarify privacy and defaults. - Adjust example container definitions in UNATTENDED_DEPLOYMENTS.md (container entries and resource values). - Change storage and flag variables and examples in BUILD_FUNC_USAGE_EXAMPLES.md (ssd-storage, var_fuse/var_tun, etc.). - Expand TOOLS_FUNC_FUNCTIONS_REFERENCE.md with many setup_* function signatures, environment vars, clarified fetch_and_deploy_gh_release modes/parameters, and additional tool docs (nodejs, php, mariadb_db, postgresql_db, java, uv, yq, meilisearch, composer, build tools). These updates improve onboarding, debugging guidance, and operational clarity for contributors and maintainers.
This commit is contained in:
CanbiZ (MickLesk)
committed by
GitHub
GitHub
parent
c576728833
commit
cb939861b8
@@ -1,197 +1,189 @@
|
||||
# **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" "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, frontend/public/json/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
|
||||
|
||||
````
|
||||
|
||||
### 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 +199,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 +219,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 +269,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.
|
||||
|
||||
@@ -5,89 +5,133 @@ source <(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxV
|
||||
# License: MIT | https://github.com/community-scripts/ProxmoxVE/raw/main/LICENSE
|
||||
# Source: [SOURCE_URL e.g. https://github.com/example/app]
|
||||
|
||||
# App Default Values
|
||||
# ============================================================================
|
||||
# APP CONFIGURATION
|
||||
# ============================================================================
|
||||
# These values are sent to build.func and define default container resources.
|
||||
# Users can customize these during installation via the interactive prompts.
|
||||
# ============================================================================
|
||||
|
||||
APP="[AppName]"
|
||||
var_tags="${var_tags:-[category]}"
|
||||
var_cpu="${var_cpu:-2}"
|
||||
var_ram="${var_ram:-2048}"
|
||||
var_disk="${var_disk:-4}"
|
||||
var_os="${var_os:-debian}"
|
||||
var_version="${var_version:-12}"
|
||||
var_unprivileged="${var_unprivileged:-1}"
|
||||
var_tags="${var_tags:-[category1];[category2]}" # Max 2 tags, semicolon-separated
|
||||
var_cpu="${var_cpu:-2}" # CPU cores: 1-4 typical
|
||||
var_ram="${var_ram:-2048}" # RAM in MB: 512, 1024, 2048, etc.
|
||||
var_disk="${var_disk:-8}" # Disk in GB: 6, 8, 10, 20 typical
|
||||
var_os="${var_os:-debian}" # OS: debian, ubuntu, alpine
|
||||
var_version="${var_version:-13}" # OS Version: 13 (Debian), 24.04 (Ubuntu), 3.21 (Alpine)
|
||||
var_unprivileged="${var_unprivileged:-1}" # 1=unprivileged (secure), 0=privileged (for Docker/Podman)
|
||||
|
||||
# =============================================================================
|
||||
# CONFIGURATION GUIDE
|
||||
# =============================================================================
|
||||
# APP - Display name, title case (e.g. "Koel", "Wallabag", "Actual Budget")
|
||||
# var_tags - Max 2 tags, semicolon separated (e.g. "music;streaming", "finance")
|
||||
# var_cpu - CPU cores: 1-4 typical
|
||||
# var_ram - RAM in MB: 512, 1024, 2048, 4096 typical
|
||||
# var_disk - Disk in GB: 4, 6, 8, 10, 20 typical
|
||||
# var_os - OS: debian, ubuntu, alpine
|
||||
# var_version - OS version: 12/13 (debian), 22.04/24.04 (ubuntu), 3.20/3.21 (alpine)
|
||||
# var_unprivileged - 1 = unprivileged (secure, default), 0 = privileged (for docker etc.)
|
||||
# ============================================================================
|
||||
# INITIALIZATION - These are required in all CT scripts
|
||||
# ============================================================================
|
||||
header_info "$APP" # Display app name and setup header
|
||||
variables # Initialize build.func variables
|
||||
color # Load color variables for output
|
||||
catch_errors # Enable error handling with automatic exit on failure
|
||||
|
||||
header_info "$APP"
|
||||
variables
|
||||
color
|
||||
catch_errors
|
||||
# ============================================================================
|
||||
# UPDATE SCRIPT - Called when user selects "Update" from web interface
|
||||
# ============================================================================
|
||||
# This function is triggered by the web interface to update the application.
|
||||
# It should:
|
||||
# 1. Check if installation exists
|
||||
# 2. Check for new GitHub releases
|
||||
# 3. Stop running services
|
||||
# 4. Backup critical data
|
||||
# 5. Deploy new version
|
||||
# 6. Run post-update commands (migrations, config updates, etc.)
|
||||
# 7. Restore data if needed
|
||||
# 8. Start services
|
||||
#
|
||||
# Exit with `exit` at the end to prevent container restart.
|
||||
# ============================================================================
|
||||
|
||||
function update_script() {
|
||||
header_info
|
||||
check_container_storage
|
||||
check_container_resources
|
||||
|
||||
# Check if installation exists
|
||||
# Step 1: Verify installation exists
|
||||
if [[ ! -d /opt/[appname] ]]; then
|
||||
msg_error "No ${APP} Installation Found!"
|
||||
exit
|
||||
fi
|
||||
|
||||
# check_for_gh_release returns 0 (true) if update available, 1 (false) if not
|
||||
if check_for_gh_release "[appname]" "[owner/repo]"; then
|
||||
msg_info "Stopping Services"
|
||||
# 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 Services"
|
||||
msg_ok "Stopped Service"
|
||||
|
||||
# Optional: Backup important data before update
|
||||
msg_info "Creating Backup"
|
||||
mkdir -p /tmp/[appname]_backup
|
||||
cp /opt/[appname]/.env /tmp/[appname]_backup/ 2>/dev/null || true
|
||||
cp -r /opt/[appname]/data /tmp/[appname]_backup/ 2>/dev/null || true
|
||||
msg_ok "Created Backup"
|
||||
# Step 4: Backup critical data before overwriting
|
||||
msg_info "Backing up Data"
|
||||
cp -r /opt/[appname]/data /opt/[appname]_data_backup 2>/dev/null || true
|
||||
msg_ok "Backed up Data"
|
||||
|
||||
# CLEAN_INSTALL=1 removes old directory before extracting new version
|
||||
CLEAN_INSTALL=1 fetch_and_deploy_gh_release "[appname]" "[owner/repo]" "tarball" "latest" "/opt/[appname]"
|
||||
# Step 5: Download and deploy new version
|
||||
# CLEAN_INSTALL=1 removes old directory before extracting
|
||||
CLEAN_INSTALL=1 fetch_and_deploy_gh_release "[appname]" "owner/repo" "tarball" "latest" "/opt/[appname]"
|
||||
|
||||
# Restore configuration and data
|
||||
# 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 /tmp/[appname]_backup/.env /opt/[appname]/ 2>/dev/null || true
|
||||
cp -r /tmp/[appname]_backup/data/* /opt/[appname]/data/ 2>/dev/null || true
|
||||
rm -rf /tmp/[appname]_backup
|
||||
cp -r /opt/[appname]_data_backup/. /opt/[appname]/data/ 2>/dev/null || true
|
||||
rm -rf /opt/[appname]_data_backup
|
||||
msg_ok "Restored Data"
|
||||
|
||||
# Optional: Run any post-update commands
|
||||
msg_info "Running Post-Update Tasks"
|
||||
cd /opt/[appname]
|
||||
# Examples:
|
||||
# $STD npm ci --production
|
||||
# $STD php artisan migrate --force
|
||||
# $STD composer install --no-dev
|
||||
msg_ok "Ran Post-Update Tasks"
|
||||
|
||||
msg_info "Starting Services"
|
||||
# Step 8: Restart service with new version
|
||||
msg_info "Starting Service"
|
||||
systemctl start [appname]
|
||||
msg_ok "Started Services"
|
||||
|
||||
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}"
|
||||
|
||||
Reference in New Issue
Block a user