Skip to main content

​
Welcome Contributors

Thank you for your interest in contributing to Proxmox VE Helper Scripts! This guide will walk you through the setup process and help you make your first contribution.
All contributors should fork the repository and work in their own fork. Never commit directly to the main repository.

​
Quick Start Guide

1

Fork the Repository

Visit community-scripts/ProxmoxVE on GitHub and click the Fork button in the top right corner.
2

Clone Your Fork

Clone your forked repository to your local machine:
git clone https://github.com/YOUR_USERNAME/ProxmoxVE.git
cd ProxmoxVE
3

Run Fork Setup Script

This critical step configures all links to point to your fork for testing:
bash docs/contribution/setup-fork.sh --full
This script modifies 600+ files to update curl URLs. You’ll need to use cherry-pick when submitting PRs (covered in the guidelines).
The script automatically:
  • Detects your GitHub username from git config
  • Updates all hardcoded links to point to your fork
  • Creates .git-setup-info with your configuration
  • Backs up modified files with .backup extension
4

Add Upstream Remote

Configure the upstream repository to sync with the main project:
git remote add upstream https://github.com/community-scripts/ProxmoxVE.git
git remote -v  # Verify both origin (your fork) and upstream are configured
5

Create a Feature Branch

Always work in a feature branch, never directly in main:
git checkout -b feature/my-awesome-app

​
Understanding the Repository Structure

The repository is organized into several key directories:

ct/

Container creation scripts that run on the Proxmox host. These scripts set up the container and call installation scripts.

install/

Installation scripts that run inside containers. These perform the actual application installation.

frontend/public/json/

JSON metadata files for the website. Each application needs a corresponding JSON file.

misc/

Shared function libraries used across all scripts, including build.func, tools.func, and install.func.

​
Development Tools Setup

​
Required Tools

  1. Git - Version control (already installed on most systems)
  2. A text editor - VS Code recommended
  3. Access to a Proxmox VE instance - For testing your scripts
If using Visual Studio Code, install these extensions:

​
Creating Your First Contribution

​
Choose Your Contribution Type

Adding a new application to the project:
# Copy templates
cp docs/contribution/templates_ct/AppName.sh ct/myapp.sh
cp docs/contribution/templates_install/AppName-install.sh install/myapp-install.sh
cp docs/contribution/templates_json/AppName.json frontend/public/json/myapp.json

# Edit the files according to your application
Study existing scripts in the same category as your application before starting. They provide excellent real-world examples.

​
Testing Your Changes

CRITICAL: You MUST test via curl from GitHub, not by running local files with bash ct/myapp.sh.

​
Why Test Via Curl?

The scripts download dependencies and other files from GitHub during execution. Testing locally bypasses these downloads, meaning you won’t catch broken URLs.

​
Proper Testing Workflow

1

Push to Your Fork

git add ct/myapp.sh install/myapp-install.sh frontend/public/json/myapp.json
git commit -m "feat: add MyApp container script"
git push origin feature/my-awesome-app
2

Wait for GitHub

GitHub takes 10-30 seconds to update files after pushing. Be patient!
3

Test Via Curl

On your Proxmox host, run:
bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/ct/myapp.sh)"
This downloads and executes the script from GitHub, testing the real URLs that users will access.
4

Verify Installation

  • Check that the container was created successfully
  • Verify the application is accessible at the displayed URL
  • Test any update functionality
  • Confirm no errors in the installation process

​
Testing with Developer Mode

For debugging, use developer mode flags: 
# Enable trace output for maximum verbosity
dev_mode="trace" bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/ct/myapp.sh)"

# Keep container even if build fails (for debugging)
dev_mode="keep" bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/ct/myapp.sh)"

# Combine multiple flags
dev_mode="trace,keep,logs" bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/ct/myapp.sh)"
Available flags:
  • trace - Enables set -x for detailed execution logs
  • keep - Prevents container deletion on failure
  • pause - Pauses at key points for inspection
  • logs - Saves detailed logs to /var/log/community-scripts/

​
Example Contribution Workflow

Here’s a complete example of adding a new application: 
# 1. Create feature branch
git checkout -b feature/add-example-app

# 2. Copy templates
cp docs/contribution/templates_ct/AppName.sh ct/example.sh
cp docs/contribution/templates_install/AppName-install.sh install/example-install.sh
cp docs/contribution/templates_json/AppName.json frontend/public/json/example.json

# 3. Edit files (update APP name, dependencies, installation steps, etc.)
nano ct/example.sh
nano install/example-install.sh
nano frontend/public/json/example.json

# 4. Commit your changes
git add ct/example.sh install/example-install.sh frontend/public/json/example.json
git commit -m "feat: add Example App container and install scripts"

# 5. Push to your fork
git push origin feature/add-example-app

# 6. Wait 10-30 seconds, then test
bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/ct/example.sh)"

# 7. Verify everything works, then prepare PR (see guidelines)

​
Keeping Your Fork Updated

Regularly sync your fork with the upstream repository: 
# Fetch latest changes from upstream
git fetch upstream

# Switch to your main branch
git checkout main

# Rebase on upstream main
git rebase upstream/main

# Force push to your fork (if needed)
git push -f origin main

​
Common Setup Issues

Make sure you’ve forked the repository first. Visit the main repository and click the Fork button before trying to clone.
Set up SSH keys or use a personal access token:
# Generate SSH key
ssh-keygen -t ed25519 -C "[email protected]"
cat ~/.ssh/id_ed25519.pub  # Add this to GitHub Settings → SSH Keys

# Or use HTTPS with token
git remote set-url origin https://[email protected]/YOUR_USERNAME/ProxmoxVE.git
Manually configure git if auto-detection fails:
git config user.name "Your Name"
git config user.email "[email protected]"

# Then run setup-fork.sh again
bash docs/contribution/setup-fork.sh --full
Consider these options:
  • Install Proxmox in a VM (VirtualBox, KVM, VMware)
  • Use a cloud provider with Proxmox support (Hetzner, OVH)
  • Run syntax checks locally: bash -n ct/myapp.sh and shellcheck ct/myapp.sh
  • Ask maintainers to test for you (mention in PR)

​
Next Steps

Now that your environment is set up:
  1. Read the Contribution Guidelines to understand coding standards
  2. Review the Code of Conduct for community expectations
  3. Study existing scripts similar to what you want to create
  4. Start building your contribution!

​
Getting Help

GitHub Discussions

Ask questions and discuss ideas with the community

GitHub Issues

Report bugs or request features

Discord Server

Join for real-time chat and support

Documentation

Comprehensive guides in the docs/ directory
First-time contributors: Don’t hesitate to ask questions! The community is friendly and happy to help.

Build docs developers (and LLMs) love

Get started for freeTalk to us