mirror of
https://github.com/community-scripts/ProxmoxVE.git
synced 2025-09-13 07:10:51 +02:00
Add initial PR for Contributing & Coding Standard (#920)
* First Design: CONTRIBUTING * Update CONTRIBUTING.md * Update CONTRIBUTING.md * Update CONTRIBUTING.md * Update CONTRIBUTING.md * Update CONTRIBUTING.md * Update CONTRIBUTING.md * Update CONTRIBUTING.md * Update CONTRIBUTING.md * Update CONTRIBUTING.md * Ideas for CONTRIBUTING.md (#768) * Update CONTRIBUTING.md * Update CONTRIBUTING.md * Update CONTRIBUTING.md * Update CONTRIBUTING.md * Update CONTRIBUTING.md * Add files via upload * fix var_tags * add comments to AppName.sh * Rework Contributing to merge the tow existing Versions * Remove coding_standards.md * Fix broken link * Fix broken link * UPDATE contributing * UPDATE contributing * UPDATE contributing * Update * UPDATE * Update AppName.md * UPDATE CONTRIBUTING.md * UPDATE CONTRIBUTING.md * Fixing some typos * Update Co-authored-by: Sébastiaan <se_bastiaan@outlook.com> * Update Contributing --------- Co-authored-by: Michel Roegl-Brunner <73236783+michelroegl-brunner@users.noreply.github.com> Co-authored-by: Michel Roegl-Brunner <michel.roegl-brunner@htl-braunau.at> Co-authored-by: Rémi Bédard-Couture <remi.bc@outlook.com> Co-authored-by: Sébastiaan <se_bastiaan@outlook.com>
This commit is contained in:
CanbiZ
GitHub
288
.github/CONTRIBUTOR_GUIDE/ct/AppName.md
vendored
Normal file
288
.github/CONTRIBUTOR_GUIDE/ct/AppName.md
vendored
Normal file
@@ -0,0 +1,288 @@
|
||||
# **AppName<span></span>.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.
|
||||
|
||||
> [!CAUTION]
|
||||
> 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)
|
||||
```
|
||||
|
||||
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-2025 community-scripts ORG
|
||||
# Author: [YourUserName]
|
||||
# License: MIT | https://github.com/community-scripts/ProxmoxVE/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 |
|
||||
>| `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
|
||||
# App Output & Base Settings
|
||||
header_info "$APP"
|
||||
base_settings
|
||||
```
|
||||
|
||||
- `header_info`: Generates ASCII header for APP
|
||||
- `base_settings`: Allows overwriting variable values
|
||||
|
||||
## 2.3 **🛠 Core functions**
|
||||
|
||||
```bash
|
||||
# Core
|
||||
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**
|
||||
|
||||
- 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
|
||||
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
|
||||
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/
|
||||
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 a 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 "Ther is currently no automatic update function for ${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 an for new version.
|
||||
- [ ] Update function up temporary files.
|
||||
- [ ] Script ends with a helpful message for the user to reach the application.
|
||||
93
.github/CONTRIBUTOR_GUIDE/ct/AppName.sh
vendored
Normal file
93
.github/CONTRIBUTOR_GUIDE/ct/AppName.sh
vendored
Normal file
@@ -0,0 +1,93 @@
|
||||
#!/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: [YourUserName]
|
||||
# License: MIT | https://github.com/community-scripts/ProxmoxVE/raw/main/LICENSE
|
||||
# Source: [SOURCE_URL]
|
||||
|
||||
# App Default Values
|
||||
APP="[APP_NAME]"
|
||||
# Name of the app (e.g. Google, Adventurelog, Apache-Guacamole"
|
||||
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
|
||||
|
||||
# App Output & Base Settings
|
||||
header_info "$APP"
|
||||
base_settings
|
||||
|
||||
# Core
|
||||
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
|
||||
msg_info "Updating $APP"
|
||||
|
||||
# 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]
|
||||
sleep 2
|
||||
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}"
|
||||
353
.github/CONTRIBUTOR_GUIDE/install/AppName-install.md
vendored
Normal file
353
.github/CONTRIBUTOR_GUIDE/install/AppName-install.md
vendored
Normal file
@@ -0,0 +1,353 @@
|
||||
|
||||
# **AppName<span></span>-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-2025 community-scripts ORG
|
||||
# Author: [YourUserName]
|
||||
# License: MIT | https://github.com/community-scripts/ProxmoxVE/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) }')
|
||||
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 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
|
||||
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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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 <<EOF` to write configuration files in a clean and readable way.
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
cat <<EOF >/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 <<EOF` to write enviromental files in a clean and readable way.
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
cat <<EOF >/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
|
||||
86
.github/CONTRIBUTOR_GUIDE/install/AppName-install.sh
vendored
Normal file
86
.github/CONTRIBUTOR_GUIDE/install/AppName-install.sh
vendored
Normal file
@@ -0,0 +1,86 @@
|
||||
#!/usr/bin/env bash
|
||||
|
||||
# Copyright (c) 2021-2024 community-scripts ORG
|
||||
# Author: [YourUserName]
|
||||
# License: MIT
|
||||
# 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) }')
|
||||
wget -q "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 <<EOF >/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"
|
||||
|
||||
motd_ssh
|
||||
customize
|
||||
34
.github/CONTRIBUTOR_GUIDE/json/AppName.json
vendored
Normal file
34
.github/CONTRIBUTOR_GUIDE/json/AppName.json
vendored
Normal file
@@ -0,0 +1,34 @@
|
||||
{
|
||||
"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": "Deescription 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": []
|
||||
}
|
||||
13
.github/CONTRIBUTOR_GUIDE/json/AppName.md
vendored
Normal file
13
.github/CONTRIBUTOR_GUIDE/json/AppName.md
vendored
Normal file
@@ -0,0 +1,13 @@
|
||||
# **AppName<span></span>.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/ProxmoxVE/json-editor) to create this file for your application.
|
||||
Reference in New Issue
Block a user