martin/ProxmoxVE
1
0
Fork 0
mirror of https://github.com/community-scripts/ProxmoxVE synced 2025-01-25 18:16:17 +00:00
Code Issues Actions 7 Packages Projects Releases Wiki Activity

Update Contributing

Browse Source
This commit is contained in:
Michel Roegl-Brunner 2025-01-10 10:30:05 +01:00
parent d14a7d9498
commit a822531093
4 changed files with 176 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
.github/CONTRIBUTOR_GUIDE/CONTRIBUTING.md → .github/CONTRIBUTING.md vendored
View File

@ -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) - [Shell Format](https://marketplace.visualstudio.com/items?itemName=foxundermoon.shell-format)
### Important Notes ### 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. - 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 call to `community-scripts/ProxmoxVE` should be adjusted to reflect the correct fork URL.
--- ---
# 🚀 The Application Script (ct/AppName.sh) # 🚀 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. - 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) # 🛠 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. - These scripts are responsible for the installation of the application.
--- ---
## 🚀 Building Your Own Scripts ## 🚀 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 ### 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!) ### 4. Commit changes (without build.func and install.func!)
```bash ```bash
@ -99,10 +98,8 @@ Open a Pull Request from your feature branch to the main repository branch. You
## 📚 Pages ## 📚 Pages
- [Function-Overview](https://github.com/community-scripts/ProxmoxVE/wiki/Function_Overview) - [CT Template: AppName.sh](https://github.com/community-scripts/ProxmoxVE/blob/main/.github/CONTRIBUTOR_GUIDE/ct/AppName.sh)
- [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/main/.github/CONTRIBUTOR_GUIDE/install/AppName-install.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/main/.github/CONTRIBUTOR_GUIDE/json/AppName.json)
- [JSON Template: AppName.json](https://github.com/community-scripts/ProxmoxVE/blob/contributor_guide/.github/CONTRIBUTOR_GUIDE/json/AppName.json)
---

63
.github/CONTRIBUTOR_GUIDE/ct/AppName.md vendored
View File

@ -1,16 +1,42 @@
# **AppName<span></span>.sh Scripts** # **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. `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. **File Header**
### 1.1 **Shebang** ### 1.1 **Shebang**
- Use `#!/usr/bin/env bash` as the shebang. - Use `#!/usr/bin/env bash` as the shebang.
```bash ```bash
#!/usr/bin/env bash #!/usr/bin/env bash
``` ```
### 1.2 **Import Functions** ### 1.2 **Import Functions**
- Import the build.func file. - Import the build.func file.
- When developing your own script, change the URL to your own repository. - 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. > Before opening a Pull Request, change the URL to point to the community-scripts repo.
Example for development: Example for development:
```bash ```bash
source <(curl -s https://raw.githubusercontent.com/[USER]/[REPO]/refs/heads/[BRANCH]/misc/build.func) source <(curl -s https://raw.githubusercontent.com/[USER]/[REPO]/refs/heads/[BRANCH]/misc/build.func)
``` ```
Example for final script: Final script:
```bash ```bash
source <(curl -s https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/misc/build.func) source <(curl -s https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/misc/build.func)
``` ```
### 1.3 **Metadata** ### 1.3 **Metadata**
- Add clear comments for script metadata, including author, copyright, and license information. - Add clear comments for script metadata, including author, copyright, and license information.
Example: Example:
```bash ```bash
# Copyright (c) 2021-2024 community-scripts ORG # Copyright (c) 2021-2025 community-scripts ORG
# Author: [YourUserName] # Author: [YourUserName]
# License: MIT | https://github.com/community-scripts/ProxmoxVE/raw/main/LICENSE # License: MIT | https://github.com/community-scripts/ProxmoxVE/raw/main/LICENSE
# Source: [SOURCE_URL] # Source: [SOURCE_URL]
``` ```
> [!NOTE]: > [!NOTE]:
>
> - Add your username and source URL > - Add your username and source URL
> - For existing scripts, add "| Co-Author [YourUserName]" after the current author > - For existing scripts, add "| Co-Author [YourUserName]" after the current author
--- ---
## 2 **Variables and function import** ## 2 **Variables and function import**
>
> [!NOTE] > [!NOTE]
> You need to have all this set in your script, otherwise it will not work! > You need to have all this set in your script, otherwise it will not work!
### 2.1 **Default Values** ### 2.1 **Default Values**
- This section sets the default values for the container. - 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. - `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] >[!NOTE]
>Description for all Default Values >Description for all Default Values
>
>| Variable | Description | Notes | >| Variable | Description | Notes |
>|----------|-------------|-------| >|----------|-------------|-------|
>| `APP` | Application name | Must match ct\AppName.sh | >| `APP` | Application name | Must match ct\AppName.sh |
@ -67,6 +101,7 @@ Example:
>| `var_unprivileged` | Container type | 1 = Unprivileged, 0 = Privileged | >| `var_unprivileged` | Container type | 1 = Unprivileged, 0 = Privileged |
Example: Example:
```bash ```bash
APP="SnipeIT" APP="SnipeIT"
var_tags="asset-management;foss" var_tags="asset-management;foss"
@ -107,8 +142,10 @@ catch_errors
## 3 **Update function** ## 3 **Update function**
### 3.1 **Function Header** ### 3.1 **Function Header**
- If applicable write a function that updates the application and the OS in the container. - If applicable write a function that updates the application and the OS in the container.
- Each update function starts with the same code: - Each update function starts with the same code:
```bash ```bash
function update_script() { function update_script() {
header_info header_info
@ -117,20 +154,25 @@ function update_script() {
``` ```
### 3.2 **Check APP** ### 3.2 **Check APP**
- Before doing anything update-wise, check if the app is installed in the container. - Before doing anything update-wise, check if the app is installed in the container.
Example: Example:
```bash ```bash
if [[ ! -d /opt/snipe-it ]]; then if [[ ! -d /opt/snipe-it ]]; then
msg_error "No ${APP} Installation Found!" msg_error "No ${APP} Installation Found!"
exit exit
fi fi
``` ```
### 3.3 **Check version** ### 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. - 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: Example with a Github Release:
```bash ```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) }') 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 if [[ ! -f /opt/${APP}_version.txt ]] || [[ "${RELEASE}" != "$(cat /opt/${APP}_version.txt)" ]]; then
@ -142,32 +184,42 @@ Example with a Github Release:
exit exit
} }
``` ```
### 3.4 **Verbosity** ### 3.4 **Verbosity**
- Use the appropriate flag (**-q** in the examples) for a command to suppress its output. - Use the appropriate flag (**-q** in the examples) for a command to suppress its output.
Example: Example:
```bash ```bash
wget -q wget -q
unzip -q unzip -q
``` ```
- If a command does not come with this functionality use `&>/dev/null` to suppress it's output. - If a command does not come with this functionality use `&>/dev/null` to suppress it's output.
Example: Example:
```bash ```bash
php artisan migrate --force &>/dev/null php artisan migrate --force &>/dev/null
php artisan config:clear &>/dev/null php artisan config:clear &>/dev/null
``` ```
### 3.5 **Backups** ### 3.5 **Backups**
- Backup user data if necessary. - Backup user data if necessary.
- Move all user data back in the directory when the update is finished. - Move all user data back in the directory when the update is finished.
>[!NOTE] >[!NOTE]
>This is not meant to be a permanent backup >This is not meant to be a permanent backup
Example backup: Example backup:
```bash ```bash
mv /opt/snipe-it /opt/snipe-it-backup mv /opt/snipe-it /opt/snipe-it-backup
``` ```
Example config restore: Example config restore:
```bash ```bash
cp /opt/snipe-it-backup/.env /opt/snipe-it/.env 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/public/uploads/ /opt/snipe-it/public/uploads/
@ -175,15 +227,19 @@ Example config restore:
``` ```
### 3.6 **Cleanup** ### 3.6 **Cleanup**
- Do not forget to remove any temporary files/folders such as zip-files or temporary backups. - Do not forget to remove any temporary files/folders such as zip-files or temporary backups.
Example: Example:
```bash ```bash
rm -rf /opt/v${RELEASE}.zip rm -rf /opt/v${RELEASE}.zip
rm -rf /opt/snipe-it-backup rm -rf /opt/snipe-it-backup
``` ```
### 3.7 **No update function** ### 3.7 **No update function**
- In case you can not provide a update function use the following code to provide user feedback. - In case you can not provide a update function use the following code to provide user feedback.
```bash ```bash
function update_script() { function update_script() {
header_info header_info
@ -201,6 +257,7 @@ function update_script() {
--- ---
## 4 **End of the script** ## 4 **End of the script**
- `start`: Launches Whiptail dialogue - `start`: Launches Whiptail dialogue
- `build_container`: Collects and integrates user settings - `build_container`: Collects and integrates user settings
- `description`: Sets LXC container description - `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 "${INFO}${YW} Access it using the following URL:${CL}"
echo -e "${TAB}${GATEWAY}${BGN}http://${IP}${CL}" echo -e "${TAB}${GATEWAY}${BGN}http://${IP}${CL}"
``` ```
--- ---
## 5. **Contribution checklist** ## 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 functions checks if app is installed an for new version.
- [ ] Update function up temporary files. - [ ] Update function up temporary files.
- [ ] Script ends with a helpful message for the user to reach the application. - [ ] Script ends with a helpful message for the user to reach the application.

100
.github/CONTRIBUTOR_GUIDE/install/AppName-install.md vendored
View File

@ -1,10 +1,48 @@
# **AppName<span></span>-install.sh Scripts** # **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. `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. **File header**
### 1.1 **Shebang** ### 1.1 **Shebang**
- Use `#!/usr/bin/env bash` as the shebang. - Use `#!/usr/bin/env bash` as the shebang.
```bash ```bash
@ -12,22 +50,28 @@
``` ```
### 1.2 **Comments** ### 1.2 **Comments**
- Add clear comments for script metadata, including author, copyright, and license information. - Add clear comments for script metadata, including author, copyright, and license information.
- Use meaningful inline comments to explain complex commands or logic. - Use meaningful inline comments to explain complex commands or logic.
Example: Example:
```bash ```bash
# Copyright (c) 2021-2024 community-scripts ORG # Copyright (c) 2021-2025 community-scripts ORG
# Author: [YourUserName] # Author: [YourUserName]
# License: MIT # License: MIT | https://github.com/community-scripts/ProxmoxVE/raw/main/LICENSE
# Source: [SOURCE_URL] # Source: [SOURCE_URL]
``` ```
> [!NOTE]: > [!NOTE]:
>
> - Add your username > - Add your username
> - When updating/reworking scripts, add "| Co-Author [YourUserName]" > - When updating/reworking scripts, add "| Co-Author [YourUserName]"
### 1.3 **Variables and function import** ### 1.3 **Variables and function import**
- This sections adds the support for all needed functions and variables. - This sections adds the support for all needed functions and variables.
```bash ```bash
source /dev/stdin <<<"$FUNCTIONS_FILE_PATH" source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
color color
@ -37,27 +81,33 @@ setting_up_container
network_check network_check
update_os update_os
``` ```
--- ---
## 2. **Variable naming and management** ## 2. **Variable naming and management**
### 2.1 **Naming conventions** ### 2.1 **Naming conventions**
- Use uppercase names for constants and environment variables. - Use uppercase names for constants and environment variables.
- Use lowercase names for local script variables. - Use lowercase names for local script variables.
Example: Example:
```bash ```bash
DB_NAME=snipeit_db # Environment-like variable (constant) DB_NAME=snipeit_db # Environment-like variable (constant)
db_user="snipeit" # Local variable db_user="snipeit" # Local variable
``` ```
--- ---
## 3. **Dependencies** ## 3. **Dependencies**
### 3.1 **Install all at once** ### 3.1 **Install all at once**
- Install all dependencies with a single command if possible - Install all dependencies with a single command if possible
Example: Example:
```bash ```bash
$STD apt-get install -y \ $STD apt-get install -y \
curl \ curl \
@ -69,14 +119,18 @@ $STD apt-get install -y \
``` ```
### 3.2 **Collapse dependencies** ### 3.2 **Collapse dependencies**
Collapse dependencies to keep the code readable. Collapse dependencies to keep the code readable.
Example: <br> Example:
Use Use
```bash ```bash
php8.2-{bcmath,common,ctype} php8.2-{bcmath,common,ctype}
``` ```
instead of instead of
```bash ```bash
php8.2-bcmath php8.2-common php8.2-ctype 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** ## 4. **Paths to application files**
If possible install the app and all necessary files in `/opt/` 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. **Version management**
### 5.1 **Install the latest release** ### 5.1 **Install the latest release**
- Always try and install the latest release - Always try and install the latest release
- Do not hardcode any version if not absolutely necessary - Do not hardcode any version if not absolutely necessary
Example for a git release: Example for a git release:
```bash ```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) }') 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" wget -q "https://github.com/snipe/snipe-it/archive/refs/tags/v${RELEASE}.zip"
``` ```
### 5.2 **Save the version for update checks** ### 5.2 **Save the version for update checks**
- Write the installed version into a file. - 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: Example:
```bash ```bash
echo "${RELEASE}" >"/opt/AppName_version.txt" echo "${RELEASE}" >"/opt/AppName_version.txt"
``` ```
--- ---
## 6. **Input and output management** ## 6. **Input and output management**
### 6.1 **User feedback** ### 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. - Display meaningful progress messages at key stages.
Example: Example:
```bash ```bash
msg_info "Installing Dependencies" msg_info "Installing Dependencies"
$STD apt-get install ... $STD apt-get install -y ...
msg_ok "Installed Dependencies" msg_ok "Installed Dependencies"
``` ```
### 6.2 **Verbosity** ### 6.2 **Verbosity**
- Use the appropiate flag (**-q** in the examples) for a command to suppres its output - Use the appropiate flag (**-q** in the examples) for a command to suppres its output
Example: Example:
```bash ```bash
wget -q wget -q
unzip -q unzip -q
``` ```
- If a command dose not come with such a functionality use `$STD` (a custom standard redirection variable) for managing output verbosity. - If a command dose not come with such a functionality use `$STD` (a custom standard redirection variable) for managing output verbosity.
Example: Example:
```bash ```bash
$STD apt-get install -y nginx $STD apt-get install -y nginx
``` ```
@ -141,9 +209,11 @@ $STD apt-get install -y nginx
## 7. **String/File Manipulation** ## 7. **String/File Manipulation**
### 7.1 **File Manipulation** ### 7.1 **File Manipulation**
- Use `sed` to replace placeholder values in configuration files. - Use `sed` to replace placeholder values in configuration files.
Example: Example:
```bash ```bash
sed -i -e "s|^DB_DATABASE=.*|DB_DATABASE=$DB_NAME|" \ sed -i -e "s|^DB_DATABASE=.*|DB_DATABASE=$DB_NAME|" \
-e "s|^DB_USERNAME=.*|DB_USERNAME=$DB_USER|" \ -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. **Security practices**
### 8.1 **Password generation** ### 8.1 **Password generation**
- Use `openssl` to generate random passwords. - Use `openssl` to generate random passwords.
- Use only alphanumeric values to not introduce unknown behaviour. - Use only alphanumeric values to not introduce unknown behaviour.
Example: Example:
```bash ```bash
DB_PASS=$(openssl rand -base64 18 | tr -dc 'a-zA-Z0-9' | head -c13) DB_PASS=$(openssl rand -base64 18 | tr -dc 'a-zA-Z0-9' | head -c13)
``` ```
### 8.2 **File permissions** ### 8.2 **File permissions**
Explicitly set secure ownership and permissions for sensitive files. Explicitly set secure ownership and permissions for sensitive files.
Example: Example:
```bash ```bash
chown -R www-data: /opt/snipe-it chown -R www-data: /opt/snipe-it
chmod -R 755 /opt/snipe-it chmod -R 755 /opt/snipe-it
@ -177,9 +251,11 @@ chmod -R 755 /opt/snipe-it
## 9. **Service Configuration** ## 9. **Service Configuration**
### 9.1 **Configuration files** ### 9.1 **Configuration files**
Use `cat <<EOF` to write configuration files in a clean and readable way. Use `cat <<EOF` to write configuration files in a clean and readable way.
Example: Example:
```bash ```bash
cat <<EOF >/etc/nginx/conf.d/snipeit.conf cat <<EOF >/etc/nginx/conf.d/snipeit.conf
server { server {
@ -189,10 +265,13 @@ server {
} }
EOF EOF
``` ```
### 9.2 **Credential management** ### 9.2 **Credential management**
Store the generated credentials in a file. Store the generated credentials in a file.
Example: Example:
```bash ```bash
USERNAME=username USERNAME=username
PASSWORD=$(openssl rand -base64 18 | tr -dc 'a-zA-Z0-9' | head -c13) 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" echo "Password: $PASSWORD"
} >> ~/application.creds } >> ~/application.creds
``` ```
### 9.3 **Enviroment files** ### 9.3 **Enviroment files**
Use `cat <<EOF` to write enviromental files in a clean and readable way. Use `cat <<EOF` to write enviromental files in a clean and readable way.
Example: Example:
```bash ```bash
cat <<EOF >/path/to/.env cat <<EOF >/path/to/.env
VARIABLE="value" VARIABLE="value"
@ -215,9 +297,11 @@ EOF
``` ```
### 9.4 **Services** ### 9.4 **Services**
Enable affected services after configuration changes and start them right away. Enable affected services after configuration changes and start them right away.
Example: Example:
```bash ```bash
systemctl enable -q --now nginx systemctl enable -q --now nginx
``` ```
@ -227,17 +311,21 @@ systemctl enable -q --now nginx
## 10. **Cleanup** ## 10. **Cleanup**
### 10.1 **Remove temporary files** ### 10.1 **Remove temporary files**
Remove temporary files and downloads after use. Remove temporary files and downloads after use.
Example: Example:
```bash ```bash
rm -rf /opt/v${RELEASE}.zip rm -rf /opt/v${RELEASE}.zip
``` ```
### 10.2 **Autoremove and autoclean** ### 10.2 **Autoremove and autoclean**
Remove unused dependencies to reduce disk space usage. Remove unused dependencies to reduce disk space usage.
Example: Example:
```bash ```bash
apt-get -y autoremove apt-get -y autoremove
apt-get -y autoclean apt-get -y autoclean

8
.github/CONTRIBUTOR_GUIDE/json/AppName.md vendored
View File

@ -1,5 +1,13 @@
# **AppName<span></span>.json Files** # **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. `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 ## 1. JSON Generator
Use the [JSON Generator](https://community-scripts.github.io/ProxmoxVE/json-editor) to create this file for your application. Use the [JSON Generator](https://community-scripts.github.io/ProxmoxVE/json-editor) to create this file for your application.