ProxmoxVE/.github/CONTRIBUTOR_GUIDE/install/AppName-install.md

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
  • Table of Contents
  • 1. File header
    • 1.1 Shebang
    • 1.2 Comments
    • 1.3 Variables and function import
  • 2. Variable naming and management
    • 2.1 Naming conventions
  • 3. Dependencies
    • 3.1 Install all at once
    • 3.2 Collapse dependencies
  • 4. Paths to application files
  • 5. Version management
    • 5.1 Install the latest release
    • 5.2 Save the version for update checks
  • 6. Input and output management
    • 6.1 User feedback
    • 6.2 Verbosity
  • 7. String/File Manipulation
    • 7.1 File Manipulation
  • 8. Security practices
    • 8.1 Password generation
    • 8.2 File permissions
  • 9. Service Configuration
    • 9.1 Configuration files
    • 9.2 Credential management
    • 9.3 Enviroment files
    • 9.4 Services
  • 10. Cleanup
    • 10.1 Remove temporary files
    • 10.2 Autoremove and autoclean
  • 11. Best Practices Checklist
    • Example: High-Level Script Flow

1. File header

1.1 Shebang

• Use #!/usr/bin/env bash as the shebang.

#!/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:

# 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.

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:

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:

$STD apt-get install -y \
  curl \
  composer \
  git \
  sudo \
  mc \
  nginx 

3.2 Collapse dependencies

Collapse dependencies to keep the code readable.

Example: Use

php8.2-{bcmath,common,ctype}

instead of

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:

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:

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:

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:

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:

$STD apt-get install -y nginx

---

7. String/File Manipulation

7.1 File Manipulation

• Use sed to replace placeholder values in configuration files.

Example:

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:

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:

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:

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:

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:

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:

systemctl enable -q --now nginx

---

10. Cleanup

10.1 Remove temporary files

Remove temporary files and downloads after use.

Example:

rm -rf /opt/v${RELEASE}.zip

10.2 Autoremove and autoclean

Remove unused dependencies to reduce disk space usage.

Example:

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