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

# ProxmoxVE Scripts - Quick Reference

**Last Updated:** 2026-02-05  
**Document Version:** 1.0  
**Status:** Active Documentation

---

## Parallel run & verification

| What | Where |
|------|--------|
| Execution order (Wave 0→1→2→3) | [FULL_PARALLEL_EXECUTION_ORDER.md](../00-meta/FULL_PARALLEL_EXECUTION_ORDER.md) |
| Wave 1 task status | [WAVE1_COMPLETION_SUMMARY.md](../00-meta/WAVE1_COMPLETION_SUMMARY.md) |
| Wave 2/3 operator checklist | [WAVE2_WAVE3_OPERATOR_CHECKLIST.md](../00-meta/WAVE2_WAVE3_OPERATOR_CHECKLIST.md) |
| Run log | [FULL_PARALLEL_RUN_LOG.md](../archive/00-meta-pruned/FULL_PARALLEL_RUN_LOG.md) (archived) |
| Full verification | `bash scripts/verify/run-full-verification.sh` |
| E2E routing only | `bash scripts/verify/verify-end-to-end-routing.sh --profile=public` |

---

## Repository Setup

```bash
# 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`)

```bash
#!/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`)

```bash
#!/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
```bash
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
```bash
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
```bash
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

```bash
# 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)