From a8225310937b00571e01ad8cb1cc6e42da5558cd Mon Sep 17 00:00:00 2001 From: Michel Roegl-Brunner Date: Fri, 10 Jan 2025 10:30:05 +0100 Subject: [PATCH] Update Contributing --- .../{CONTRIBUTOR_GUIDE => }/CONTRIBUTING.md | 19 ++-- .github/CONTRIBUTOR_GUIDE/ct/AppName.md | 69 ++++++++++-- .../install/AppName-install.md | 102 ++++++++++++++++-- .github/CONTRIBUTOR_GUIDE/json/AppName.md | 12 ++- 4 files changed, 176 insertions(+), 26 deletions(-) rename .github/{CONTRIBUTOR_GUIDE => }/CONTRIBUTING.md (80%) diff --git a/.github/CONTRIBUTOR_GUIDE/CONTRIBUTING.md b/.github/CONTRIBUTING.md similarity index 80% rename from .github/CONTRIBUTOR_GUIDE/CONTRIBUTING.md rename to .github/CONTRIBUTING.md index 81a216b7..3b1027b1 100644 --- a/.github/CONTRIBUTOR_GUIDE/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -39,28 +39,27 @@ Before contributing, please ensure that you have the following setup: - [Shell Format](https://marketplace.visualstudio.com/items?itemName=foxundermoon.shell-format) ### Important Notes -- Use [AppName.sh](https://github.com/community-scripts/ProxmoxVE/blob/contributor_guide/.github/CONTRIBUTOR_GUIDE/ct/AppName.sh) and [AppName-install.sh](https://github.com/community-scripts/ProxmoxVE/blob/contributor_guide/.github/CONTRIBUTOR_GUIDE/install/AppName-install.sh) as templates when creating new scripts. -- The call to `community-scripts/ProxmoxVE` should be adjusted to reflect the correct fork URL. +- Use [AppName.sh](https://github.com/community-scripts/ProxmoxVE/blob/main/.github/CONTRIBUTOR_GUIDE/ct/AppName.sh) and [AppName-install.sh](https://github.com/community-scripts/ProxmoxVE/blob/main/.github/CONTRIBUTOR_GUIDE/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/ProxmoxVE/blob/contributor_guide/.github/CONTRIBUTOR_GUIDE/ct/AppName.md). +- You can find all coding standards, as well as the structure for this file [here](https://github.com/community-scripts/ProxmoxVE/blob/main/.github/CONTRIBUTOR_GUIDE/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/ProxmoxVE/blob/contributor_guide/.github/CONTRIBUTOR_GUIDE/install/AppName-install.md). +- You can find all coding standards, as well as the structure for this file [here](https://github.com/community-scripts/ProxmoxVE/blob/main/.github/CONTRIBUTOR_GUIDE/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/ProxmoxVE/blob/contributor_guide/.github/CONTRIBUTOR_GUIDE/install/AppName-install.sh) +Start with the [template script](https://github.com/community-scripts/ProxmoxVE/blob/main/.github/CONTRIBUTOR_GUIDE/install/AppName-install.sh) --- @@ -80,7 +79,7 @@ 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/ProxmoxVE/main` to `https://raw.githubusercontent.com/[USER]/[REPOSITORY]/refs/head/[BRANCH]`. 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/ProxmoxVE/main`. +To be able to develop from your own branch you need to change `https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main` to `https://raw.githubusercontent.com/[USER]/[REPOSITORY]/refs/head/[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/ProxmoxVE/main`. ### 4. Commit changes (without build.func and install.func!) ```bash @@ -99,10 +98,8 @@ Open a Pull Request from your feature branch to the main repository branch. You ## ๐Ÿ“š Pages -- [Function-Overview](https://github.com/community-scripts/ProxmoxVE/wiki/Function_Overview) -- [CT Template: AppName.sh](https://github.com/community-scripts/ProxmoxVE/blob/contributor_guide/.github/CONTRIBUTOR_GUIDE/ct/AppName.sh) -- [Install Template: AppName-install.sh](https://github.com/community-scripts/ProxmoxVE/blob/contributor_guide/.github/CONTRIBUTOR_GUIDE/install/AppName-install.sh) -- [JSON Template: AppName.json](https://github.com/community-scripts/ProxmoxVE/blob/contributor_guide/.github/CONTRIBUTOR_GUIDE/json/AppName.json) +- [CT Template: AppName.sh](https://github.com/community-scripts/ProxmoxVE/blob/main/.github/CONTRIBUTOR_GUIDE/ct/AppName.sh) +- [Install Template: AppName-install.sh](https://github.com/community-scripts/ProxmoxVE/blob/main/.github/CONTRIBUTOR_GUIDE/install/AppName-install.sh) +- [JSON Template: AppName.json](https://github.com/community-scripts/ProxmoxVE/blob/main/.github/CONTRIBUTOR_GUIDE/json/AppName.json) ---- diff --git a/.github/CONTRIBUTOR_GUIDE/ct/AppName.md b/.github/CONTRIBUTOR_GUIDE/ct/AppName.md index b9b2fe72..20d28d86 100644 --- a/.github/CONTRIBUTOR_GUIDE/ct/AppName.md +++ b/.github/CONTRIBUTOR_GUIDE/ct/AppName.md @@ -1,16 +1,42 @@ # **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. @@ -18,43 +44,51 @@ > Before opening a Pull Request, change the URL to point to the community-scripts repo. Example for development: + ```bash source <(curl -s https://raw.githubusercontent.com/[USER]/[REPO]/refs/heads/[BRANCH]/misc/build.func) ``` -Example for final script: +Final script: + ```bash source <(curl -s https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/misc/build.func) ``` ### 1.3 **Metadata** + - Add clear comments for script metadata, including author, copyright, and license information. Example: + ```bash -# Copyright (c) 2021-2024 community-scripts ORG +# Copyright (c) 2021-2025 community-scripts ORG # Author: [YourUserName] # License: MIT | https://github.com/community-scripts/ProxmoxVE/raw/main/LICENSE # Source: [SOURCE_URL] ``` -> [!NOTE]: +> [!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! +- `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 | @@ -67,6 +101,7 @@ Example: >| `var_unprivileged` | Container type | 1 = Unprivileged, 0 = Privileged | Example: + ```bash APP="SnipeIT" var_tags="asset-management;foss" @@ -107,8 +142,10 @@ catch_errors ## 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 @@ -117,20 +154,25 @@ function update_script() { ``` ### 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** -- Befoer updating, check if a new version exists. + +- Befoer 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 @@ -142,32 +184,42 @@ Example with a Github Release: exit } ``` + ### 3.4 **Verbosity** + - Use the appropriate flag (**-q** in the examples) for a command to suppress its output. Example: + ```bash wget -q unzip -q ``` + - If a command does not come with this functionality use `&>/dev/null` to suppress it's output. Example: + ```bash php artisan migrate --force &>/dev/null php artisan config:clear &>/dev/null ``` ### 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/ @@ -175,15 +227,19 @@ Example config restore: ``` ### 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 a update function use the following code to provide user feedback. + ```bash function update_script() { header_info @@ -201,6 +257,7 @@ function update_script() { --- ## 4 **End of the script** + - `start`: Launches Whiptail dialogue - `build_container`: Collects and integrates user settings - `description`: Sets LXC container description @@ -216,6 +273,7 @@ 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** @@ -228,4 +286,3 @@ echo -e "${TAB}${GATEWAY}${BGN}http://${IP}${CL}" - [ ] Update functions checks if app is installed an for new version. - [ ] Update function up temporary files. - [ ] Script ends with a helpful message for the user to reach the application. - diff --git a/.github/CONTRIBUTOR_GUIDE/install/AppName-install.md b/.github/CONTRIBUTOR_GUIDE/install/AppName-install.md index 701e7cc3..241cd99a 100644 --- a/.github/CONTRIBUTOR_GUIDE/install/AppName-install.md +++ b/.github/CONTRIBUTOR_GUIDE/install/AppName-install.md @@ -1,10 +1,48 @@ # **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 @@ -12,22 +50,28 @@ ``` ### 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-2024 community-scripts ORG +# Copyright (c) 2021-2025 community-scripts ORG # Author: [YourUserName] -# License: MIT +# License: MIT | https://github.com/community-scripts/ProxmoxVE/raw/main/LICENSE # Source: [SOURCE_URL] ``` -> [!NOTE]: + +> [!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 @@ -37,27 +81,33 @@ 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 \ @@ -69,14 +119,18 @@ $STD apt-get install -y \ ``` ### 3.2 **Collapse dependencies** + Collapse dependencies to keep the code readable. -Example:
+Example: Use + ```bash php8.2-{bcmath,common,ctype} ``` + instead of + ```bash php8.2-bcmath php8.2-common php8.2-ctype ``` @@ -84,6 +138,7 @@ 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/` --- @@ -91,47 +146,60 @@ 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) }') wget -q "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 updates +- 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` and `msg_ok` to print status messages. + +- 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 ... +$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 wget -q 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 ``` @@ -141,9 +209,11 @@ $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|" \ @@ -155,18 +225,22 @@ sed -i -e "s|^DB_DATABASE=.*|DB_DATABASE=$DB_NAME|" \ ## 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 @@ -177,9 +251,11 @@ chmod -R 755 /opt/snipe-it ## 9. **Service Configuration** ### 9.1 **Configuration files** + Use `cat </etc/nginx/conf.d/snipeit.conf server { @@ -189,10 +265,13 @@ server { } 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) @@ -202,10 +281,13 @@ PASSWORD=$(openssl rand -base64 18 | tr -dc 'a-zA-Z0-9' | head -c13) echo "Password: $PASSWORD" } >> ~/application.creds ``` + ### 9.3 **Enviroment files** + Use `cat </path/to/.env VARIABLE="value" @@ -215,9 +297,11 @@ EOF ``` ### 9.4 **Services** + Enable affected services after configuration changes and start them right away. Example: + ```bash systemctl enable -q --now nginx ``` @@ -227,17 +311,21 @@ 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 diff --git a/.github/CONTRIBUTOR_GUIDE/json/AppName.md b/.github/CONTRIBUTOR_GUIDE/json/AppName.md index e91afe1f..5b61f5e9 100644 --- a/.github/CONTRIBUTOR_GUIDE/json/AppName.md +++ b/.github/CONTRIBUTOR_GUIDE/json/AppName.md @@ -1,5 +1,13 @@ # **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. - ## 1. JSON Generator -Use the [JSON Generator](https://community-scripts.github.io/ProxmoxVE/json-editor) to create this file for your application. \ No newline at end of file +## 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/ProxmoxVE/json-editor) to create this file for your application.