proxmox/docs/12-quick-reference/QUICK_REFERENCE.md

ProxmoxVE Scripts - Quick Reference

Repository Setup

# Clone as submodule (already done)
git submodule add https://github.com/community-scripts/ProxmoxVE.git ProxmoxVE

# Update submodule
git submodule update --init --recursive

# Update to latest
cd ProxmoxVE && git pull origin main && cd ..

Script Locations

• Container Scripts: ProxmoxVE/ct/AppName.sh
• Install Scripts: ProxmoxVE/install/AppName-install.sh
• Function Libraries: ProxmoxVE/misc/*.func
• Documentation: ProxmoxVE/docs/

Quick Script Template

Container Script (ct/AppName.sh)

#!/usr/bin/env bash
source <(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/misc/build.func)
# Copyright (c) 2021-2025 community-scripts ORG
# Author: YourUsername
# License: MIT

APP="AppName"
var_tags="tag1;tag2"
var_cpu="2"
var_ram="2048"
var_disk="10"
var_os="debian"
var_version="12"
var_unprivileged="1"

header_info "$APP"
variables
color
catch_errors

function update_script() {
    header_info
    check_container_storage
    check_container_resources
    if [[ ! -f /path/to/installation ]]; then
        msg_error "No ${APP} Installation Found!"
        exit
    fi
    # Update logic
    exit
}

start
build_container
description
msg_ok "Completed Successfully!\n"

Install Script (install/AppName-install.sh)

#!/usr/bin/env bash
# Copyright (c) 2021-2025 community-scripts ORG

source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
color
verb_ip6
catch_errors
setting_up_container
network_check
update_os

msg_info "Installing Dependencies"
$STD apt-get install -y curl sudo mc package1 package2
msg_ok "Installed Dependencies"

msg_info "Setting up ${APP}"
# Installation steps here
echo "${RELEASE}" >/opt/${APP}_version.txt
msg_ok "Setup ${APP}"

motd_ssh
customize

Key Functions

Message Functions

• msg_info "message" - Info message
• msg_ok "message" - Success message
• msg_error "message" - Error message
• msg_warn "message" - Warning message

Execution

• $STD command - Silent execution (respects VERBOSE)
• silent command - Execute with error handling

Container Functions

• build_container - Create and setup container
• description - Set container description
• check_container_storage - Verify storage
• check_container_resources - Verify resources

Variable Precedence

1. Environment variables (highest)
2. App-specific defaults (/defaults/<app>.vars)
3. User global defaults (/default.vars)
4. Built-in defaults (lowest)

Installation Modes

• Mode 0: Default (built-in defaults)
• Mode 1: Advanced (19-step wizard)
• Mode 2: User defaults
• Mode 3: App defaults
• Mode 4: Settings menu

Common Patterns

Version Detection

RELEASE=$(curl -fsSL https://api.github.com/repos/user/repo/releases/latest | \
  grep "tag_name" | awk '{print substr($2, 2, length($2)-3)}')

Database Setup

DB_PASS=$(openssl rand -base64 18 | tr -dc 'a-zA-Z0-9' | head -c13)
$STD mysql -u root -e "CREATE DATABASE $DB_NAME;"

Systemd Service

cat <<EOF >/etc/systemd/system/${APP}.service
[Unit]
Description=${APP} Service
After=network.target
[Service]
ExecStart=/path/to/command
Restart=always
[Install]
WantedBy=multi-user.target
EOF
systemctl enable -q --now ${APP}.service

Documentation Links

• Main Docs: ProxmoxVE/docs/README.md
• Container Guide: ProxmoxVE/docs/ct/DETAILED_GUIDE.md
• Install Guide: ProxmoxVE/docs/install/DETAILED_GUIDE.md
• Contribution: ProxmoxVE/docs/contribution/README.md
• Technical Ref: ProxmoxVE/docs/TECHNICAL_REFERENCE.md

Testing

# Test container script
bash ProxmoxVE/ct/AppName.sh

# Test with verbose mode
VERBOSE=yes bash ProxmoxVE/ct/AppName.sh

# Test update function
bash ProxmoxVE/ct/AppName.sh -u

Contribution Checklist

• Use template from docs/contribution/templates_*/
• Follow naming: AppName.sh and AppName-install.sh
• Include copyright header
• Use msg_* functions for messages
• Use $STD for command execution
• Quote all variables
• Test on Proxmox VE 8.4+ or 9.0+
• Implement update function (if applicable)
• Update documentation (if needed)