Proxmox VE Helper-Scripts Deployment & Usage Guide

1. Prerequisites

System Requirements

• Proxmox VE Server: Version 8.4.x, 9.0.x, or 9.1.x
• Operating System: Debian-based Linux with Proxmox Tools installed
• Network: Internet connection for downloading scripts and dependencies
• Shell Access: SSH or direct console access to Proxmox host
• Permissions: Root or sudo privileges for installation

Software Dependencies

• curl: For downloading installation scripts
• bash: Shell interpreter (version 4.0+)
• Proxmox Tools: pveversion should show compatible version

2. Installation

Method 1: Web-Based Installation (Recommended)

1. Visit helper-scripts.com
2. Browse or search for your desired application/script
3. Copy the provided bash command from the script page
4. Connect to your Proxmox server via SSH or console
5. Paste and execute the command:

# Example command format (actual command varies by script)
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/scripts/[script-name].sh)"

Method 2: Local Script Manager

Install the PVEScripts-Local manager for direct Proxmox UI integration:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/pve-scripts-local.sh)"

This adds a menu to your Proxmox interface for accessing scripts without visiting the website.

Method 3: Manual Installation

For development or custom deployments:

1. Clone the repository:

git clone https://github.com/community-scripts/ProxmoxVE.git
cd ProxmoxVE

2. Explore available scripts:

ls -la scripts/          # Main installation scripts
ls -la ct/              # Container templates and helpers

3. Run a specific script directly:

./scripts/home-assistant.sh

3. Configuration

Environment Setup

Most scripts handle configuration automatically, but you may need:

1. Network Configuration:

   • Ensure proper bridge or VLAN configuration in Proxmox
   • Static IP assignment or DHCP availability

2. Storage Setup:

   • Adequate storage space on your Proxmox host
   • Appropriate storage type (LVM-Thin, ZFS, Directory)

3. Resource Allocation:

   • CPU cores (minimum 2 recommended for most applications)
   • RAM allocation (varies by application, typically 2GB+)
   • Disk space (20GB+ for most containers)

Script-Specific Configuration

Each script may have unique configuration options. During installation, you'll typically be prompted for:

• Container/VM Name: Custom identifier
• Resource Limits: CPU, memory, disk space
• Network Settings: IP address, gateway, DNS
• Application Settings: Ports, credentials, features

Configuration Files Location

• Global Configuration: /etc/pve-scripts/ (if using local manager)
• Script-Specific Configs: Usually within the container at /config/
• Proxmox Settings: Managed through Proxmox web interface

4. Build & Run (Development)

Frontend Development Setup

The project includes a Next.js frontend for the web interface:

1. Install Node.js dependencies:

cd frontend
npm install

2. Set up environment variables:

cp .env.example .env.local
# Edit .env.local with your configuration

3. Run development server:

npm run dev

4. Build for production:

npm run build
npm start

Backend/API Development

The API serves script metadata and categories:

1. JSON data structure is in public/json/ directory
2. API routes are defined in src/app/api/
3. Types are defined in src/lib/types.ts

Adding New Scripts

1. Create a new JSON file in public/json/ following the schema:

{
  "name": "Application Name",
  "slug": "application-name",
  "categories": [1, 2],
  "date_created": "2024-01-01",
  "type": "ct",
  "updateable": true,
  "privileged": false,
  "interface_port": 8080,
  "documentation": "https://docs.example.com",
  "website": "https://example.com",
  "logo": "https://logo.url",
  "config_path": "/config",
  "description": "Application description",
  "install_methods": [
    {
      "type": "default",
      "script": "bash -c \"$(curl -fsSL https://install.url)\"",
      "resources": {
        "cpu": 2,
        "ram": 2048,
        "hdd": 20,
        "os": "debian-12",
        "version": "latest"
      }
    }
  ],
  "default_credentials": {
    "username": "admin",
    "password": "admin"
  },
  "notes": [
    {
      "text": "Important note",
      "type": "warning"
    }
  ]
}

2. Update metadata in public/json/metadata.json
3. Test the script installation process

5. Deployment

Production Deployment Options

Option A: Self-Hosted Web Interface

1. Build the frontend:

cd frontend
npm run build

2. Deploy to a hosting service:

   • Vercel: Optimized for Next.js
   • Netlify: Simple static deployment
   • Docker Container: Package as a container image

3. Set up CI/CD (GitHub Actions example):

name: Deploy
on:
  push:
    branches: [main]
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm ci && npm run build
      - uses: vercel/action@latest
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}

Option B: Proxmox Integration Deployment

1. Package scripts for Proxmox template distribution
2. Create LXC container templates with pre-installed applications
3. Set up local repository mirror for offline installations

Option C: Docker Deployment

FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/public ./public
COPY --from=builder /app/package*.json ./
RUN npm ci --only=production
EXPOSE 3000
CMD ["npm", "start"]

Environment Variables

For web interface deployment:

NEXT_PUBLIC_API_URL=https://api.yourdomain.com
NEXT_PUBLIC_SITE_URL=https://helper-scripts.com
# Add any additional API keys or configuration

6. Troubleshooting

Common Installation Issues

Issue: "Command not found" or script fails to download

Solution:

# Ensure curl is installed
apt update && apt install -y curl

# Check internet connectivity
ping -c 3 github.com

# Try with wget as alternative
bash -c "$(wget -qO- https://raw.githubusercontent.com/...)"

Issue: Proxmox version incompatible

Solution:

# Check Proxmox version
pveversion

# Update Proxmox if needed
apt update && apt dist-upgrade

Issue: Container fails to start

Solution:

1. Check container logs:

pct console <CTID> --log

2. Verify resource availability:

# Check host resources
free -h
df -h

3. Ensure proper permissions:

# Check if privileged container is needed
pct config <CTID> | grep unprivileged

Issue: Network connectivity problems

Solution:

1. Verify Proxmox network configuration:

cat /etc/network/interfaces

2. Check firewall rules:

iptables -L -n -v

3. Test DNS resolution within container:

pct exec <CTID> -- nslookup google.com

Script-Specific Troubleshooting

Web Interface Not Loading

1. Check if the service is running:

systemctl status pve-scripts-local

2. Verify port configuration:

netstat -tulpn | grep :3000

3. Check application logs:

journalctl -u pve-scripts-local -f

Update Problems

1. Clear script cache:

rm -rf /tmp/pve-scripts-*

2. Force re-download:

curl -fsSL https://raw.githubusercontent.com/... | bash -s -- --force

Getting Help

1. Check Documentation: Visit helper-scripts.com
2. Community Support: Join the Discord
3. GitHub Issues: Report bugs at GitHub Issues
4. Discussions: Feature requests at GitHub Discussions

Maintenance Tips

• Regularly update Proxmox VE to latest stable version
• Monitor script updates through the web interface
• Backup container configurations before major updates
• Test new scripts in a non-production environment first
• Join the community Discord for real-time support and updates