martin/ProxmoxVE
1
0
Fork 0
mirror of https://github.com/community-scripts/ProxmoxVE synced 2025-01-10 19:05:09 +00:00
Code Issues Actions 8 Packages Projects Releases Wiki Activity

Update

Browse Source 
Co-authored-by: Sébastiaan <se_bastiaan@outlook.com>
This commit is contained in:
Michel Roegl-Brunner 2024-12-29 15:35:00 +01:00 committed by GitHub
parent acd26c4747
commit d14a7d9498
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
5 changed files with 95 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
.github/CONTRIBUTOR_GUIDE/CONTRIBUTING.md vendored
View File

@ -2,7 +2,7 @@
# Community Scripts Contribution Guide # Community Scripts Contribution Guide
## **Welcome to the communty-scripts Repository!** ## **Welcome to the communty-scripts Repository!**
📜 These documents outlines the essential coding standards for all our scripts and JSON files. Adhering to these standards ensures that our codebase remains consistent, readable, and maintainable. By following these guidelines, we can improve collaboration, reduce errors, and enhance the overall quality of our project. 📜 These documents outline the essential coding standards for all our scripts and JSON files. Adhering to these standards ensures that our codebase remains consistent, readable, and maintainable. By following these guidelines, we can improve collaboration, reduce errors, and enhance the overall quality of our project.
### Why Coding Standards Matter ### Why Coding Standards Matter
@ -15,11 +15,11 @@ Coding standards are crucial for several reasons:
### Scope of These Documents ### Scope of These Documents
These documents covers the coding standards for the following types of files in our project: These documents cover the coding standards for the following types of files in our project:
- **`APP-install.sh` Scripts**: These scripts are responsible for the installation of applications and are located in the `/install` directory. - **`install/$AppName-install.sh` Scripts**: These scripts are responsible for the installation of applications.
- **`APP.sh` Scripts**: These scripts handle the creation and updating of containers and are found in the `/ct` directory. - **`ct/$AppName.sh` Scripts**: These scripts handle the creation and updating of containers.
- **JSON Files**: These files store structured data and are located in the `/json` directory. - **`json/$AppName.json`**: These files store structured data and are used for the website.
Each section provides detailed guidelines on various aspects of coding, including shebang usage, comments, variable naming, function naming, indentation, error handling, command substitution, quoting, script structure, and logging. Additionally, examples are provided to illustrate the application of these standards. Each section provides detailed guidelines on various aspects of coding, including shebang usage, comments, variable naming, function naming, indentation, error handling, command substitution, quoting, script structure, and logging. Additionally, examples are provided to illustrate the application of these standards.
@ -46,14 +46,14 @@ Before contributing, please ensure that you have the following setup:
# 🚀 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 files [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/contributor_guide/.github/CONTRIBUTOR_GUIDE/ct/AppName.md).
- These Scripts are responsible for container creation, setting the necessary variables and handles the update of the application. - 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 files [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/contributor_guide/.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.
--- ---
@ -66,34 +66,34 @@ Start with the [template script](https://github.com/community-scripts/ProxmoxVE/
## 🤝 Contribution Process ## 🤝 Contribution Process
### 1. Fork the Repository ### 1. Fork the repository
Fork to your GitHub account Fork to your GitHub account
### 2. Clone Your Fork on your Pc ### 2. Clone your fork on your local environment
```bash ```bash
git clone https://github.com/yourUserName/ForkName git clone https://github.com/yourUserName/ForkName
``` ```
### 3. Create a New Branch ### 3. Create a new branch
```bash ```bash
git switch -c your-feature-branch 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
You need to switch `https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main` to `https://raw.githubusercontent.com/[USER]/[REPOSITORY]/refs/head/[BRANCH]` to test your script in your repository. Before opening a Pull Request change all this back to point to the community-scripts Repository. 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`.
### 4. Commit Changes (without build.func and install.func!) ### 4. Commit changes (without build.func and install.func!)
```bash ```bash
git commit -m "Your commit message" git commit -m "Your commit message"
``` ```
### 5. Push to Your Fork ### 5. Push to your fork
```bash ```bash
git push origin your-feature-branch git push origin your-feature-branch
``` ```
### 6. Create a Pull Request ### 6. Create a Pull Request
Open a PR from your feature branch to the main repository branch. You may only include your **AppName.sh**, **AppName-install.sh** and **AppName.json** files in the 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.
--- ---

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

@ -1,5 +1,5 @@
# **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.
## 1. **File Header** ## 1. **File Header**
@ -11,18 +11,18 @@
#!/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 link to your own repository. - When developing your own script, change the URL to your own repository.
> [!CAUTION] > [!CAUTION]
> Before opening a Pull Request, change the link 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: Example for 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)
``` ```
@ -44,13 +44,13 @@ Example:
--- ---
## 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 sections 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 represent 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]
@ -78,7 +78,7 @@ var_version="12"
var_unprivileged="1" var_unprivileged="1"
``` ```
## 2.2 **📋 App Output & Base Settings** ## 2.2 **📋 App output & base settings**
```bash ```bash
# App Output & Base Settings # App Output & Base Settings
@ -89,7 +89,7 @@ base_settings
- `header_info`: Generates ASCII header for APP - `header_info`: Generates ASCII header for APP
- `base_settings`: Allows overwriting variable values - `base_settings`: Allows overwriting variable values
## 2.3 **🛠 Core Functions** ## 2.3 **🛠 Core functions**
```bash ```bash
# Core # Core
@ -104,11 +104,11 @@ catch_errors
--- ---
## 3 **Update Function** ## 3 **Update function**
### 3.1 **Function Header** ### 3.1 **Function Header**
- If applicable write a function wich 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 a standardised Header: - Each update function starts with the same code:
```bash ```bash
function update_script() { function update_script() {
header_info header_info
@ -117,7 +117,7 @@ function update_script() {
``` ```
### 3.2 **Check APP** ### 3.2 **Check APP**
- Befor doing anything updatewise, 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
@ -126,9 +126,9 @@ if [[ ! -d /opt/snipe-it ]]; then
exit exit
fi fi
``` ```
### 3.3 **Check Version** ### 3.3 **Check version**
- Befor updating, check if a new Version exists. - Befoer updating, check if a new version exists.
- For this we use the `${APPLICATION}_version.txt` file created in `/opt` during the install. - 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
@ -143,13 +143,13 @@ Example with a Github Release:
} }
``` ```
### 3.4 **Verbosity** ### 3.4 **Verbosity**
- Use the appropiate flag (**-q** in the examples) for a command to suppres 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 dose not come with such a functionality use `&>/dev/null` to suppress its output. - If a command does not come with this functionality use `&>/dev/null` to suppress it's output.
Example: Example:
```bash ```bash
@ -158,10 +158,10 @@ php artisan config:clear &>/dev/null
``` ```
### 3.5 **Backups** ### 3.5 **Backups**
- Backup userdata if nessesary. - Backup user data if necessary.
- Move all userdata back in the Directory when the update is finnished. - Move all user data back in the directory when the update is finished.
>[!NOTE] >[!NOTE]
>This is not meant to be a permantent backup >This is not meant to be a permanent backup
Example backup: Example backup:
```bash ```bash
@ -200,11 +200,11 @@ 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
- With `echo -e "${TAB}${GATEWAY}${BGN}http://${IP}${CL}"` you can point the user to the IP:PORT/folder needed to access the App. - 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 ```bash
start start
@ -218,14 +218,14 @@ echo -e "${TAB}${GATEWAY}${BGN}http://${IP}${CL}"
``` ```
--- ---
## 5. **Best Practices Checklist** ## 5. **Contribution checklist**
- [ ] Shebang is correctly set (`#!/usr/bin/env bash`). - [ ] Shebang is correctly set (`#!/usr/bin/env bash`).
- [ ] Correct link to *build.func* - [ ] Correct link to *build.func*
- [ ] Metadata (author, license) is included at the top. - [ ] Metadata (author, license) is included at the top.
- [ ] Variables follow naming conventions. - [ ] Variables follow naming conventions.
- [ ] Update function exists. - [ ] Update function exists.
- [ ] 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 helpfull message for the User to reach the App. - [ ] Script ends with a helpful message for the user to reach the application.

8
.github/CONTRIBUTOR_GUIDE/ct/AppName.sh vendored
View File

@ -7,21 +7,21 @@ source <(curl -s https://raw.githubusercontent.com/community-scripts/ProxmoxVE/m
# App Default Values # App Default Values
APP="[APP_NAME]" APP="[APP_NAME]"
# Name of the App (e.g. Google, Adventurelog, Apache-Guacamole" # Name of the app (e.g. Google, Adventurelog, Apache-Guacamole"
TAGS="[TAGS]" TAGS="[TAGS]"
# Tags for Proxmox VE, maximum 2 pcs., no spaces allowed, separated by a semicolon ; (e.g. database | adblock;dhcp) # Tags for Proxmox VE, maximum 2 pcs., no spaces allowed, separated by a semicolon ; (e.g. database | adblock;dhcp)
var_cpu="[CPU]" var_cpu="[CPU]"
# Number of Cores (1-X) (e.g. 4) - default are 2 # Number of cores (1-X) (e.g. 4) - default are 2
var_ram="[RAM]" var_ram="[RAM]"
# Amount of used RAM in MB (e.g. 2048 or 4096) # Amount of used RAM in MB (e.g. 2048 or 4096)
var_disk="[DISK]" var_disk="[DISK]"
# Amount of used Disk Space in GB (e.g. 4 or 10) # Amount of used disk space in GB (e.g. 4 or 10)
var_os="[OS]" var_os="[OS]"
# Default OS (e.g. debian, ubuntu, alpine) # Default OS (e.g. debian, ubuntu, alpine)
var_version="[VERSION]" var_version="[VERSION]"
# Default OS version (e.g. 12 for debian, 24.04 for ubuntu, 3.20 for alpine) # Default OS version (e.g. 12 for debian, 24.04 for ubuntu, 3.20 for alpine)
var_unprivileged="[UNPRIVILEGED]" var_unprivileged="[UNPRIVILEGED]"
# 1 = unprivileged Container, 0 = privileged Container # 1 = unprivileged container, 0 = privileged container
# App Output & Base Settings # App Output & Base Settings
header_info "$APP" header_info "$APP"

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

@ -1,8 +1,8 @@
# **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.
## 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.
@ -26,7 +26,7 @@ Example:
> - 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"
@ -39,9 +39,9 @@ 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.
@ -68,8 +68,8 @@ $STD apt-get install -y \
nginx nginx
``` ```
### 3.2 **Collaps Dependencies** ### 3.2 **Collapse dependencies**
- Collaps dependencies to keep the Code readable. Collapse dependencies to keep the code readable.
Example: <br> Example: <br>
Use Use
@ -83,26 +83,26 @@ php8.2-bcmath php8.2-common php8.2-ctype
--- ---
## 4. **Paths to applications** ## 4. **Paths to application files**
- If possible install the App and all nessesery files in `/opt/` 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 if possibly - Always try and install the latest release
- Do not hardcode any version if not absolutly nessesery - 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 **Store the Version in a File for later Updates** ### 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 app.sh to check if we need to update or not - This is used for the update function in AppName.sh to check for updates
Example: Example:
```bash ```bash
@ -110,9 +110,9 @@ 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` and `msg_ok` to print status messages.
- Display meaningful progress messages at key stages. - Display meaningful progress messages at key stages.
@ -152,19 +152,19 @@ 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 secure tools (e.g., `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
@ -176,8 +176,8 @@ 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
@ -189,8 +189,9 @@ 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
@ -201,8 +202,10 @@ 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 **Enviromental 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:
```bash ```bash
cat <<EOF >/path/to/.env cat <<EOF >/path/to/.env
VARIABLE="value" VARIABLE="value"
@ -212,7 +215,7 @@ EOF
``` ```
### 9.4 **Services** ### 9.4 **Services**
- Enable affected services after configuration changes and start it right away. Enable affected services after configuration changes and start them right away.
Example: Example:
```bash ```bash
@ -223,16 +226,16 @@ systemctl enable -q --now nginx
## 10. **Cleanup** ## 10. **Cleanup**
### 10.1 **Remove Temporary Files** ### 10.1 **Remove temporary files**
- Remove temporary files or unnecessary 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**
- Clean up unused dependencies to reduce disk space usage. Remove unused dependencies to reduce disk space usage.
Example: Example:
```bash ```bash
@ -255,8 +258,8 @@ apt-get -y autoclean
### Example: High-Level Script Flow ### Example: High-Level Script Flow
1. **Dependencies Installation** 1. Dependencies installation
2. **Database Setup** 2. Database setup
3. **Download and Configure Application** 3. Download and configure application
4. **Service Configuration** 4. Service configuration
5. **Final Cleanup** 5. Final cleanup

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

@ -1,5 +1,5 @@
# **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 frontend. 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.
## 1 **Json Generator** ## 1. JSON Generator
- To spare you some headache creating the json file, use the [Json-Editor](https://community-scripts.github.io/ProxmoxVE/json-editor) Use the [JSON Generator](https://community-scripts.github.io/ProxmoxVE/json-editor) to create this file for your application.