From 66bc2bcfc217d70440cbf6a01f7f3dfd7cc785ee Mon Sep 17 00:00:00 2001 From: Michel Roegl-Brunner <73236783+michelroegl-brunner@users.noreply.github.com> Date: Wed, 25 Mar 2026 13:46:01 +0100 Subject: [PATCH 1/5] Revise contributing guidelines and remove outdated info Updated the contributing guidelines for clarity and conciseness. --- .../CONTRIBUTOR_AND_GUIDES/CONTRIBUTING.md | 78 +------------------ 1 file changed, 2 insertions(+), 76 deletions(-) diff --git a/.github/CONTRIBUTOR_AND_GUIDES/CONTRIBUTING.md b/.github/CONTRIBUTOR_AND_GUIDES/CONTRIBUTING.md index 1c5f20b5..a34d405f 100644 --- a/.github/CONTRIBUTOR_AND_GUIDES/CONTRIBUTING.md +++ b/.github/CONTRIBUTOR_AND_GUIDES/CONTRIBUTING.md @@ -14,9 +14,7 @@ Coding standards are crucial for several reasons: 3. **Maintainability**: Code that follows a standard structure is easier to refactor and update. It ensures that changes can be made with minimal risk of introducing new bugs. 4. **Collaboration**: When everyone follows the same standards, it becomes easier to collaborate on code. It reduces friction and misunderstandings during code reviews and merges. -### Scope of These Documents - -These documents cover the coding standards for the following types of files in our project: +### Scope of These Docs - **`install/$AppName-install.sh` Scripts**: These scripts are responsible for the installation of applications. - **`ct/$AppName.sh` Scripts**: These scripts handle the creation and updating of containers. @@ -31,76 +29,4 @@ Let's work together to keep our codebase clean, efficient, and maintainable! ## Getting Started -Before contributing, please ensure that you have the following setup: - -1. **Visual Studio Code** (recommended for script development) -2. **Recommended VS Code Extensions:** - - [Shell Syntax](https://marketplace.visualstudio.com/items?itemName=bmalehorn.shell-syntax) - - [ShellCheck](https://marketplace.visualstudio.com/items?itemName=timonwong.shellcheck) - - [Shell Format](https://marketplace.visualstudio.com/items?itemName=foxundermoon.shell-format) - -### Important Notes -- Use [AppName.sh](https://github.com/community-scripts/ProxmoxVED/blob/main/.github/CONTRIBUTOR_AND_GUIDES/ct/AppName.sh) and [AppName-install.sh](https://github.com/community-scripts/ProxmoxVED/blob/main/.github/CONTRIBUTOR_AND_GUIDES/install/AppName-install.sh) as templates when creating new scripts. - ---- - -# πŸš€ The Application Script (ct/AppName.sh) - -- You can find all coding standards, as well as the structure for this file [here](https://github.com/community-scripts/ProxmoxVED/blob/main/.github/CONTRIBUTOR_AND_GUIDES/ct/AppName.md). -- These scripts are responsible for container creation, setting the necessary variables and handling the update of the application once installed. - ---- - -# πŸ›  The Installation Script (install/AppName-install.sh) - -- You can find all coding standards, as well as the structure for this file [here](https://github.com/community-scripts/ProxmoxVED/blob/main/.github/CONTRIBUTOR_AND_GUIDES/install/AppName-install.md). -- These scripts are responsible for the installation of the application. - ---- - -## πŸš€ Building Your Own Scripts - -Start with the [template script](https://github.com/community-scripts/ProxmoxVED/blob/main/.github/CONTRIBUTOR_AND_GUIDES/install/AppName-install.sh) - ---- - -## 🀝 Contribution Process - -### 1. Fork the repository -Fork to your GitHub account - -### 2. Clone your fork on your local environment -```bash -git clone https://github.com/yourUserName/ForkName -``` - -### 3. Create a new branch -```bash -git switch -c your-feature-branch -``` - -### 4. Change paths in build.func install.func and AppName.sh -To be able to develop from your own branch you need to change `https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main` to `https://raw.githubusercontent.com/[USER]/[REPOSITORY]/refs/heads/[BRANCH]`. You need to make this change atleast in misc/build.func misc/install.func and in your ct/AppName.sh. This change is only for testing. Before opening a Pull Request you should change this line change all this back to point to `https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main`. - -### 4. Commit changes (without build.func and install.func!) -```bash -git commit -m "Your commit message" -``` - -### 5. Push to your fork -```bash -git push origin your-feature-branch -``` - -### 6. Create a Pull Request -Open a Pull Request from your feature branch to the main repository branch. You must only include your **$AppName.sh**, **$AppName-install.sh** and **$AppName.json** files in the pull request. - ---- - -## πŸ“š Pages - -- [CT Template: AppName.sh](https://github.com/community-scripts/ProxmoxVED/blob/main/.github/CONTRIBUTOR_AND_GUIDES/ct/AppName.sh) -- [Install Template: AppName-install.sh](https://github.com/community-scripts/ProxmoxVED/blob/main/.github/CONTRIBUTOR_AND_GUIDES/install/AppName-install.sh) -- [JSON Template: AppName.json](https://github.com/community-scripts/ProxmoxVED/blob/main/.github/CONTRIBUTOR_AND_GUIDES/json/AppName.json) - - +Find all needed Information in our [Docs]([https://duckduckgo.com](https://community-scripts.org/docs) From 3ad666a9aa89fe8d53cffc4e076b0048e1b7fc1d Mon Sep 17 00:00:00 2001 From: Michel Roegl-Brunner <73236783+michelroegl-brunner@users.noreply.github.com> Date: Wed, 25 Mar 2026 13:46:17 +0100 Subject: [PATCH 2/5] Delete .github/CONTRIBUTOR_AND_GUIDES/json directory --- .../CONTRIBUTOR_AND_GUIDES/json/AppName.json | 34 ------------------- .../CONTRIBUTOR_AND_GUIDES/json/AppName.md | 13 ------- 2 files changed, 47 deletions(-) delete mode 100644 .github/CONTRIBUTOR_AND_GUIDES/json/AppName.json delete mode 100644 .github/CONTRIBUTOR_AND_GUIDES/json/AppName.md diff --git a/.github/CONTRIBUTOR_AND_GUIDES/json/AppName.json b/.github/CONTRIBUTOR_AND_GUIDES/json/AppName.json deleted file mode 100644 index 746ebd91..00000000 --- a/.github/CONTRIBUTOR_AND_GUIDES/json/AppName.json +++ /dev/null @@ -1,34 +0,0 @@ -{ - "name": "AppName", - "slug": "appname", - "categories": [ - 0 - ], - "date_created": "DATE CREATED", - "type": "ct", - "updateable": true, - "privileged": false, - "interface_port": DEFAULT-PORT, - "documentation": null, - "website": "LINK TO WEBSITE", - "logo": "LINK TO LOGO", - "description": "Description of the app", - "install_methods": [ - { - "type": "default", - "script": "ct/AppName.sh", - "resources": { - "cpu": 2, - "ram": 2048, - "hdd": 4, - "os": "debian", - "version": "12" - } - } - ], - "default_credentials": { - "username": null, - "password": null - }, - "notes": [] -} \ No newline at end of file diff --git a/.github/CONTRIBUTOR_AND_GUIDES/json/AppName.md b/.github/CONTRIBUTOR_AND_GUIDES/json/AppName.md deleted file mode 100644 index 0082e38f..00000000 --- a/.github/CONTRIBUTOR_AND_GUIDES/json/AppName.md +++ /dev/null @@ -1,13 +0,0 @@ -# **AppName.json Files** - - `AppName.json` files found in the `/json` directory. These files are used to provide informations for the website. For this guide we take `/json/snipeit.json` as example. - -## Table of Contents - -- [**AppName.json Files**](#appnamejson-files) - - [Table of Contents](#table-of-contents) - - [1. JSON Generator](#1-json-generator) - -## 1. JSON Generator - -Use the [JSON Generator](https://community-scripts.github.io/ProxmoxVED/json-editor) to create this file for your application. From 3b3edc9c6244e80941a0a99ec00ef0f93b1544a5 Mon Sep 17 00:00:00 2001 From: Michel Roegl-Brunner <73236783+michelroegl-brunner@users.noreply.github.com> Date: Wed, 25 Mar 2026 13:46:25 +0100 Subject: [PATCH 3/5] Delete .github/CONTRIBUTOR_AND_GUIDES/install directory --- .../install/AppName-install.md | 353 ------------------ .../install/AppName-install.sh | 83 ---- 2 files changed, 436 deletions(-) delete mode 100644 .github/CONTRIBUTOR_AND_GUIDES/install/AppName-install.md delete mode 100644 .github/CONTRIBUTOR_AND_GUIDES/install/AppName-install.sh diff --git a/.github/CONTRIBUTOR_AND_GUIDES/install/AppName-install.md b/.github/CONTRIBUTOR_AND_GUIDES/install/AppName-install.md deleted file mode 100644 index 8e23af37..00000000 --- a/.github/CONTRIBUTOR_AND_GUIDES/install/AppName-install.md +++ /dev/null @@ -1,353 +0,0 @@ - -# **AppName-install.sh Scripts** - - `AppName-install.sh` scripts found in the `/install` directory. These scripts are responsible for the installation of the application. For this guide we take `/install/snipeit-install.sh` as example. - -## Table of Contents - -- [**AppName-install.sh Scripts**](#appname-installsh-scripts) - - [Table of Contents](#table-of-contents) - - [1. **File header**](#1-file-header) - - [1.1 **Shebang**](#11-shebang) - - [1.2 **Comments**](#12-comments) - - [1.3 **Variables and function import**](#13-variables-and-function-import) - - [2. **Variable naming and management**](#2-variable-naming-and-management) - - [2.1 **Naming conventions**](#21-naming-conventions) - - [3. **Dependencies**](#3-dependencies) - - [3.1 **Install all at once**](#31-install-all-at-once) - - [3.2 **Collapse dependencies**](#32-collapse-dependencies) - - [4. **Paths to application files**](#4-paths-to-application-files) - - [5. **Version management**](#5-version-management) - - [5.1 **Install the latest release**](#51-install-the-latest-release) - - [5.2 **Save the version for update checks**](#52-save-the-version-for-update-checks) - - [6. **Input and output management**](#6-input-and-output-management) - - [6.1 **User feedback**](#61-user-feedback) - - [6.2 **Verbosity**](#62-verbosity) - - [7. **String/File Manipulation**](#7-stringfile-manipulation) - - [7.1 **File Manipulation**](#71-file-manipulation) - - [8. **Security practices**](#8-security-practices) - - [8.1 **Password generation**](#81-password-generation) - - [8.2 **File permissions**](#82-file-permissions) - - [9. **Service Configuration**](#9-service-configuration) - - [9.1 **Configuration files**](#91-configuration-files) - - [9.2 **Credential management**](#92-credential-management) - - [9.3 **Enviroment files**](#93-enviroment-files) - - [9.4 **Services**](#94-services) - - [10. **Cleanup**](#10-cleanup) - - [10.1 **Remove temporary files**](#101-remove-temporary-files) - - [10.2 **Autoremove and autoclean**](#102-autoremove-and-autoclean) - - [11. **Best Practices Checklist**](#11-best-practices-checklist) - - [Example: High-Level Script Flow](#example-high-level-script-flow) - -## 1. **File header** - -### 1.1 **Shebang** - -- Use `#!/usr/bin/env bash` as the shebang. - -```bash -#!/usr/bin/env bash -``` - -### 1.2 **Comments** - -- Add clear comments for script metadata, including author, copyright, and license information. -- Use meaningful inline comments to explain complex commands or logic. - -Example: - -```bash -# Copyright (c) 2021-2026 community-scripts ORG -# Author: [YourUserName] -# License: MIT | https://github.com/community-scripts/ProxmoxVED/raw/main/LICENSE -# Source: [SOURCE_URL] -``` - -> [!NOTE]: -> -> - Add your username -> - When updating/reworking scripts, add "| Co-Author [YourUserName]" - -### 1.3 **Variables and function import** - -- This sections adds the support for all needed functions and variables. - -```bash -source /dev/stdin <<<"$FUNCTIONS_FILE_PATH" -color -verb_ip6 -catch_errors -setting_up_container -network_check -update_os -``` - ---- - -## 2. **Variable naming and management** - -### 2.1 **Naming conventions** - -- Use uppercase names for constants and environment variables. -- Use lowercase names for local script variables. - -Example: - -```bash -DB_NAME=snipeit_db # Environment-like variable (constant) -db_user="snipeit" # Local variable -``` - ---- - -## 3. **Dependencies** - -### 3.1 **Install all at once** - -- Install all dependencies with a single command if possible - -Example: - -```bash -$STD apt-get install -y \ - curl \ - composer \ - git \ - sudo \ - mc \ - nginx -``` - -### 3.2 **Collapse dependencies** - -Collapse dependencies to keep the code readable. - -Example: -Use - -```bash -php8.2-{bcmath,common,ctype} -``` - -instead of - -```bash -php8.2-bcmath php8.2-common php8.2-ctype -``` - ---- - -## 4. **Paths to application files** - -If possible install the app and all necessary files in `/opt/` - ---- - -## 5. **Version management** - -### 5.1 **Install the latest release** - -- Always try and install the latest release -- Do not hardcode any version if not absolutely necessary - -Example for a git 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) }') -curl -fsSL "https://github.com/snipe/snipe-it/archive/refs/tags/v${RELEASE}.zip" -``` - -### 5.2 **Save the version for update checks** - -- Write the installed version into a file. -- This is used for the update function in **AppName.sh** to check for if a Update is needed. - -Example: - -```bash -echo "${RELEASE}" >"/opt/AppName_version.txt" -``` - ---- - -## 6. **Input and output management** - -### 6.1 **User feedback** - -- Use standard functions like `msg_info`, `msg_ok` or `msg_error` to print status messages. -- Each `msg_info` must be followed with a `msg_ok` before any other output is made. -- Display meaningful progress messages at key stages. - -Example: - -```bash -msg_info "Installing Dependencies" -$STD apt-get install -y ... -msg_ok "Installed Dependencies" -``` - -### 6.2 **Verbosity** - -- Use the appropiate flag (**-q** in the examples) for a command to suppres its output -Example: - -```bash -curl -fsSL -unzip -q -``` - -- If a command dose not come with such a functionality use `$STD` (a custom standard redirection variable) for managing output verbosity. - -Example: - -```bash -$STD apt-get install -y nginx -``` - ---- - -## 7. **String/File Manipulation** - -### 7.1 **File Manipulation** - -- Use `sed` to replace placeholder values in configuration files. - -Example: - -```bash -sed -i -e "s|^DB_DATABASE=.*|DB_DATABASE=$DB_NAME|" \ - -e "s|^DB_USERNAME=.*|DB_USERNAME=$DB_USER|" \ - -e "s|^DB_PASSWORD=.*|DB_PASSWORD=$DB_PASS|" .env -``` - ---- - -## 8. **Security practices** - -### 8.1 **Password generation** - -- Use `openssl` to generate random passwords. -- Use only alphanumeric values to not introduce unknown behaviour. - -Example: - -```bash -DB_PASS=$(openssl rand -base64 18 | tr -dc 'a-zA-Z0-9' | head -c13) -``` - -### 8.2 **File permissions** - -Explicitly set secure ownership and permissions for sensitive files. - -Example: - -```bash -chown -R www-data: /opt/snipe-it -chmod -R 755 /opt/snipe-it -``` - ---- - -## 9. **Service Configuration** - -### 9.1 **Configuration files** - -Use `cat </etc/nginx/conf.d/snipeit.conf -server { - listen 80; - root /opt/snipe-it/public; - index index.php; -} -EOF -``` - -### 9.2 **Credential management** - -Store the generated credentials in a file. - -Example: - -```bash -USERNAME=username -PASSWORD=$(openssl rand -base64 18 | tr -dc 'a-zA-Z0-9' | head -c13) -{ - echo "Application-Credentials" - echo "Username: $USERNAME" - echo "Password: $PASSWORD" -} >> ~/application.creds -``` - -### 9.3 **Enviroment files** - -Use `cat </path/to/.env -VARIABLE="value" -PORT=3000 -DB_NAME="${DB_NAME}" -EOF -``` - -### 9.4 **Services** - -Enable affected services after configuration changes and start them right away. - -Example: - -```bash -systemctl enable -q --now nginx -``` - ---- - -## 10. **Cleanup** - -### 10.1 **Remove temporary files** - -Remove temporary files and downloads after use. - -Example: - -```bash -rm -rf /opt/v${RELEASE}.zip -``` - -### 10.2 **Autoremove and autoclean** - -Remove unused dependencies to reduce disk space usage. - -Example: - -```bash -apt-get -y autoremove -apt-get -y autoclean -``` - ---- - -## 11. **Best Practices Checklist** - -- [ ] Shebang is correctly set (`#!/usr/bin/env bash`). -- [ ] Metadata (author, license) is included at the top. -- [ ] Variables follow naming conventions. -- [ ] Sensitive values are dynamically generated. -- [ ] Files and services have proper permissions. -- [ ] Script cleans up temporary files. - ---- - -### Example: High-Level Script Flow - -1. Dependencies installation -2. Database setup -3. Download and configure application -4. Service configuration -5. Final cleanup diff --git a/.github/CONTRIBUTOR_AND_GUIDES/install/AppName-install.sh b/.github/CONTRIBUTOR_AND_GUIDES/install/AppName-install.sh deleted file mode 100644 index eb573fa3..00000000 --- a/.github/CONTRIBUTOR_AND_GUIDES/install/AppName-install.sh +++ /dev/null @@ -1,83 +0,0 @@ -#!/usr/bin/env bash - -# Copyright (c) 2021-2026 community-scripts ORG -# Author: [YourUserName] -# License: MIT | https://github.com/community-scripts/ProxmoxVED/raw/main/LICENSE -# Source: [SOURCE_URL] - -# Import Functions und Setup -source /dev/stdin <<<"$FUNCTIONS_FILE_PATH" -color -verb_ip6 -catch_errors -setting_up_container -network_check -update_os - -# Installing Dependencies with the 3 core dependencies (curl;sudo;mc) -msg_info "Installing Dependencies" -$STD apt-get install -y \ - curl \ - sudo \ - mc \ - [PACKAGE_1] \ - [PACKAGE_2] \ - [PACKAGE_3] -msg_ok "Installed Dependencies" - -# Template: MySQL Database -msg_info "Setting up Database" -DB_NAME=[DB_NAME] -DB_USER=[DB_USER] -DB_PASS=$(openssl rand -base64 18 | tr -dc 'a-zA-Z0-9' | head -c13) -$STD mysql -u root -e "CREATE DATABASE $DB_NAME;" -$STD mysql -u root -e "CREATE USER '$DB_USER'@'localhost' IDENTIFIED WITH mysql_native_password AS PASSWORD('$DB_PASS');" -$STD mysql -u root -e "GRANT ALL ON $DB_NAME.* TO '$DB_USER'@'localhost'; FLUSH PRIVILEGES;" -{ - echo "${APPLICATION} Credentials" - echo "Database User: $DB_USER" - echo "Database Password: $DB_PASS" - echo "Database Name: $DB_NAME" -} >>~/$APP_NAME.creds -msg_ok "Set up Database" - -# Temp - -# Setup App -msg_info "Setup ${APPLICATION}" -RELEASE=$(curl -s https://api.github.com/repos/[REPO]/releases/latest | grep "tag_name" | awk '{print substr($2, 2, length($2)-3) }') -curl -fsSL "https://github.com/[REPO]/archive/refs/tags/${RELEASE}.zip" -unzip -q ${RELEASE}.zip -mv ${APPLICATION}-${RELEASE}/ /opt/${APPLICATION} -# -# -# -echo "${RELEASE}" >/opt/${APPLICATION}_version.txt -msg_ok "Setup ${APPLICATION}" - -# Creating Service (if needed) -msg_info "Creating Service" -cat </etc/systemd/system/${APPLICATION}.service -[Unit] -Description=${APPLICATION} Service -After=network.target - -[Service] -ExecStart=[START_COMMAND] -Restart=always - -[Install] -WantedBy=multi-user.target -EOF -systemctl enable -q --now ${APPLICATION}.service -msg_ok "Created Service" - -motd_ssh -customize - -# Cleanup -msg_info "Cleaning up" -rm -f ${RELEASE}.zip -$STD apt-get -y autoremove -$STD apt-get -y autoclean -msg_ok "Cleaned" From ad2f1bc8794197b76de7540ed697aaece7867ec8 Mon Sep 17 00:00:00 2001 From: Michel Roegl-Brunner <73236783+michelroegl-brunner@users.noreply.github.com> Date: Wed, 25 Mar 2026 13:46:38 +0100 Subject: [PATCH 4/5] Delete .github/CONTRIBUTOR_AND_GUIDES/ct directory --- .github/CONTRIBUTOR_AND_GUIDES/ct/AppName.md | 286 ------------------- .github/CONTRIBUTOR_AND_GUIDES/ct/AppName.sh | 86 ------ 2 files changed, 372 deletions(-) delete mode 100644 .github/CONTRIBUTOR_AND_GUIDES/ct/AppName.md delete mode 100644 .github/CONTRIBUTOR_AND_GUIDES/ct/AppName.sh diff --git a/.github/CONTRIBUTOR_AND_GUIDES/ct/AppName.md b/.github/CONTRIBUTOR_AND_GUIDES/ct/AppName.md deleted file mode 100644 index 8507c7c2..00000000 --- a/.github/CONTRIBUTOR_AND_GUIDES/ct/AppName.md +++ /dev/null @@ -1,286 +0,0 @@ -# **AppName.sh Scripts** - - `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 -s https://raw.githubusercontent.com/[USER]/[REPO]/refs/heads/[BRANCH]/misc/build.func) -``` - -Final script: - -```bash -source <(curl -s https://raw.githubusercontent.com/community-scripts/ProxmoxVED/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/ProxmoxVED/raw/main/LICENSE -# Source: [SOURCE_URL] -``` - -> [!NOTE]: -> -> - Add your username and source URL -> - For existing scripts, add "| Co-Author [YourUserName]" after the current author - ---- - -## 2 **Variables and function import** -> -> [!NOTE] -> You need to have all this set in your script, otherwise it will not work! - -### 2.1 **Default Values** - -- 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! - ->[!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 | - -Example: - -```bash -APP="SnipeIT" -var_tags="asset-management;foss" -var_cpu="2" -var_ram="2048" -var_disk="4" -var_os="debian" -var_version="12" -var_unprivileged="1" -``` - -## 2.2 **πŸ“‹ App output & base settings** - -```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 - ---- - -## 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: - -```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 -} -``` - -### 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. diff --git a/.github/CONTRIBUTOR_AND_GUIDES/ct/AppName.sh b/.github/CONTRIBUTOR_AND_GUIDES/ct/AppName.sh deleted file mode 100644 index cf9333c4..00000000 --- a/.github/CONTRIBUTOR_AND_GUIDES/ct/AppName.sh +++ /dev/null @@ -1,86 +0,0 @@ -#!/usr/bin/env bash -source <(curl -s https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/misc/build.func) -# Copyright (c) 2021-2026 community-scripts ORG -# Author: [YourUserName] -# License: MIT | https://github.com/community-scripts/ProxmoxVED/raw/main/LICENSE -# Source: [SOURCE_URL] - -# App Default Values -APP="[APP_NAME]" -# Name of the app (e.g. Google, Adventurelog, Apache-Guacamole" -var_tags="[TAGS]" -# Tags for Proxmox VE, maximum 2 pcs., no spaces allowed, separated by a semicolon ; (e.g. database | adblock;dhcp) -var_cpu="[CPU]" -# Number of cores (1-X) (e.g. 4) - default are 2 -var_ram="[RAM]" -# Amount of used RAM in MB (e.g. 2048 or 4096) -var_disk="[DISK]" -# Amount of used disk space in GB (e.g. 4 or 10) -var_os="[OS]" -# Default OS (e.g. debian, ubuntu, alpine) -var_version="[VERSION]" -# Default OS version (e.g. 12 for debian, 24.04 for ubuntu, 3.20 for alpine) -var_unprivileged="[UNPRIVILEGED]" -# 1 = unprivileged container, 0 = privileged container - -header_info "$APP" -variables -color -catch_errors - -function update_script() { - header_info - check_container_storage - check_container_resources - - # Check if installation is present | -f for file, -d for folder - if [[ ! -f [INSTALLATION_CHECK_PATH] ]]; then - msg_error "No ${APP} Installation Found!" - exit - fi - - # Crawling the new version and checking whether an update is required - RELEASE=$(curl -fsSL [RELEASE_URL] | [PARSE_RELEASE_COMMAND]) - if [[ "${RELEASE}" != "$(cat /opt/${APP}_version.txt)" ]] || [[ ! -f /opt/${APP}_version.txt ]]; then - # Stopping Services - msg_info "Stopping $APP" - systemctl stop [SERVICE_NAME] - msg_ok "Stopped $APP" - - # Creating Backup - msg_info "Creating Backup" - tar -czf "/opt/${APP}_backup_$(date +%F).tar.gz" [IMPORTANT_PATHS] - msg_ok "Backup Created" - - # Execute Update - msg_info "Updating $APP to v${RELEASE}" - [UPDATE_COMMANDS] - msg_ok "Updated $APP to v${RELEASE}" - - # Starting Services - msg_info "Starting $APP" - systemctl start [SERVICE_NAME] - msg_ok "Started $APP" - - # Cleaning up - msg_info "Cleaning Up" - rm -rf [TEMP_FILES] - msg_ok "Cleanup Completed" - - # Last Action - echo "${RELEASE}" >/opt/${APP}_version.txt - msg_ok "Update Successful" - else - msg_ok "No update required. ${APP} is already at v${RELEASE}" - fi - exit -} - -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}:[PORT]${CL}" From 5d1fecf1449b83d14580d113872f173e014a5c2e Mon Sep 17 00:00:00 2001 From: Michel Roegl-Brunner <73236783+michelroegl-brunner@users.noreply.github.com> Date: Wed, 25 Mar 2026 13:47:28 +0100 Subject: [PATCH 5/5] Add community contribution section to README Added a section inviting community contributions and linking to documentation. --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index 967e7139..50a26ff2 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,12 @@ This repository contains a collection of scripts for managing and automating Pro --- +## Want to help? + +Follow [here](https://community-scripts.org/docs) to see our Documentations. + +--- + ## πŸš€ Development Status - **⚠️ Unstable**: Features may be incomplete or subject to change.