diff --git a/.github/CONTRIBUTOR_GUIDE/CONTRIBUTING.md b/.github/CONTRIBUTOR_GUIDE/CONTRIBUTING.md index f64ead99..d0b10237 100644 --- a/.github/CONTRIBUTOR_GUIDE/CONTRIBUTING.md +++ b/.github/CONTRIBUTOR_GUIDE/CONTRIBUTING.md @@ -20,23 +20,146 @@ Before contributing, please ensure that you have the following setup: --- -## Structure of Installation Scripts +## Structure of Installation Scripts (ct/AppName.sh) All installation scripts should follow this standard structure: ### 1. File Header ```bash #!/usr/bin/env bash - +source <(curl -s https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/misc/build.func) # Copyright (c) 2021-2024 community-scripts ORG -# Author: tteck (tteckster) -# License: MIT -# https://github.com/community-scripts/ProxmoxVE/raw/main/LICENSE +# Author: [YourUserName] +# License: MIT | https://github.com/community-scripts/ProxmoxVE/raw/main/LICENSE +# Source: [SOURCE_URL] ``` -### 2. Initial Setup +- You only need to add here your username & the source_url (website of the AppName-Project or github) +- if this an existing Script set after the current Author an "| Co-Author [YourUserName]" + +### 2. App Default Values +```bash +# App Default Values +APP="[APP_NAME]" +TAGS="[TAGS]" +var_cpu="[CPU]" +var_ram="[RAM]" +var_disk="[DISKSIZE]" +var_os="[OS]" +var_version="[VERSION]" +var_unprivileged="[UNPRIVILEGED]" +``` + +=> You need here to increase all values. +An Special Value is missing in default, because its not needed in every script and need to remove before create an PR: +=> var_verbose="yes|no" - that enable the verbose mode, and you can see all outputs of the Script. + +Declaration of values: +- APP => Is the name of the application, must match the ct\AppName.sh +- TAGS => These are tags that are displayed in Proxmox (colored dots). Do not use too many! +- var_cpu => Number of used CPU-Cores +- var_ram => Number of used RAM in MB +- var_disk => Number of hard disk capacities used in GB +- var_os => Operating system (alpine | debian | ubuntu) +- var_version => Version of OS (3.20 | 11;12 | 20.04, 22.04, 24.04, 24.10) +- var_unprivileged => 1 = UNPRIVILEGED LXC Container | 0 = PRIVILEGED LXC Container + +=> Following Values are default by build.func: +- TAGS="community-script" (is default, not need to add this, only new TAGS) +- var_cpu="1" +- var_ram="1024" +- var_disk="4" +- var_unprivileged="1" +- var_verbose="no" + +Example: +```bash +# App Default Values +APP="Google" +TAGS="searching;website" +var_cpu="2" +var_ram="4096" +var_disk="10" +var_os="debian" +var_version="12" +var_unprivileged="0" +``` +=> That Create an privileged LXC with name "google" (ct\google.sh) with 2 CPU Cores, 4096 MB RAM, 10 GB HDD Space, in Debian 12. + +### 3. App Output & Base Settings +```bash +# App Output & Base Settings +header_info "$APP" +base_settings +``` + +- header_info is an function created in build.func and set the "APP" Value into an ASCII-Header. +- base_settings are used to overwrite the variable values of 2. or to accept all other default values. + +### 4. Core +```bash +# Core +variables +color +catch_errors +``` + +- variables is an build.func function that This function processes the input and prepares variables for further use in the script. +- color is an build.func function that sets all icons, colors and formattings in the scripts. +- catch_errors is an build.func function that enables error handling in the script by setting options and defining a trap for the ERR signal. + +### 5. Update-Script Part +```bash +function update_script() { + header_info + check_container_storage + check_container_resources + + # Update-Code +} +``` + +- header_info called the ASCII-Generated AppName with every call of the function +- check_container_storage check the available storage and give output if it to less +- check_container_resources check the ressources (var_cpu / var_ram) if it to less and give user Output + +Then comes the whole update function of the Script himself. + +### 6. Script-End +```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}:[PORT]${CL}" +``` + +- "start" is an build.func function to start the Whiptail Dialogue for Update or Create LXC +- "build_container" is an build.func function, this function collects user settings and integrates all the collected information. +- "description" is an build.func function, sets the description of the LXC container + + +## Structure of Installation Scripts (install/AppName-install.sh) + +All installation scripts should follow this standard structure: + +### 1. File Header Every script should source the functions file and run these initial checks: +```bash +#!/usr/bin/env bash + +# Copyright (c) 2021-2024 community-scripts ORG +# Author: [YourUserName] +# License: MIT | https://github.com/community-scripts/ProxmoxVE/raw/main/LICENSE +``` +- You only need to add here your username +- if this an existing Script set after the current Author an "| Co-Author [YourUserName]" + +### 2. Import Functions und Setup ```bash source /dev/stdin <<< "$FUNCTIONS_FILE_PATH" color @@ -62,9 +185,9 @@ msg_ok "Installed Dependencies" Use heredoc (`cat </etc/systemd/system/service.service +cat </etc/systemd/system/${APPLICATION}.service [Unit] -Description=Service Description +Description=${APPLICATION} Service Description After=network.target [Service]