Contributing to Proxmox VE Helper-Scripts

Welcome! We're glad you want to contribute. This guide covers everything you need to add new scripts, improve existing ones, or help in other ways.

For detailed coding standards and full documentation, visit community-scripts.org/docs.

How Can I Help?

Important

New scripts must always be submitted to ProxmoxVED first — not to this repository. PRs with new scripts opened directly against ProxmoxVE will be closed without review. Bug fixes, improvements, and features for existing scripts go here (ProxmoxVE).

I want to…	Where to go
Add a brand-new script	ProxmoxVED — testing repo for new scripts
Fix a bug or improve an existing script	This repo (ProxmoxVE) — open a PR here
Add a feature to an existing script	This repo (ProxmoxVE) — open a PR here
Report a bug or broken script	Open an Issue
Request a new script or feature	Start a Discussion
Report a security vulnerability	Security Policy
Chat with contributors	Discord

Prerequisites

Before writing scripts, we recommend setting up:

Visual Studio Code with these extensions:

Script Structure

Every script consists of two files:

File	Purpose
`ct/AppName.sh`	Container creation, variable setup, and update handling
`install/AppName-install.sh`	Application installation logic

Use existing scripts in ct/ and install/ as reference. Full coding standards and annotated templates are at community-scripts.org/docs/contribution.

Contribution Process

Adding a new script

New scripts are not accepted directly in this repository. The workflow is:

Fork ProxmoxVED and clone it
Create a branch: git switch -c feat/myapp
Write your two script files:
- ct/myapp.sh
- install/myapp-install.sh
Test thoroughly in ProxmoxVED — run the script against a real Proxmox instance
Open a PR in ProxmoxVED for review and testing
Once accepted and verified there, the script will be promoted to ProxmoxVE by maintainers

Follow the coding standards at community-scripts.org/docs/contribution.

Fixing a bug or improving an existing script

Changes to scripts that already exist in ProxmoxVE go directly here:

Fork this repository (ProxmoxVE) and clone it:

git clone https://github.com/YOUR_USERNAME/ProxmoxVE
cd ProxmoxVE

Create a branch:
```
git switch -c fix/myapp-description
```
Make your changes to the relevant files in ct/ and/or install/
Open a PR from your fork to community-scripts/ProxmoxVE/main

Your PR should only contain the files you changed. Do not include unrelated modifications.

Code Standards

Key rules at a glance:

One script per service — keep them focused
Naming convention: lowercase, hyphen-separated (my-app.sh)
Shebang: #!/usr/bin/env bash
Quote all variables: "$VAR" not $VAR
Use lowercase variable names
Do not hardcode credentials or sensitive values

Full standards and examples: community-scripts.org/docs/contribution

Developer Mode & Debugging

Set the dev_mode variable to enable debugging features when testing. Flags can be combined (comma-separated):

dev_mode="trace,keep" bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/myapp.sh)"

Flag	Description
`trace`	Enables `set -x` for maximum verbosity during execution
`keep`	Prevents the container from being deleted if the build fails
`pause`	Pauses execution at key points before customization
`breakpoint`	Drops to a shell at hardcoded `breakpoint` calls in scripts
`logs`	Saves detailed build logs to `/var/log/community-scripts/`
`dryrun`	Bypasses actual container creation (limited support)
`motd`	Forces an update of the Message of the Day

Notes

Website metadata (name, description, logo, tags) is managed via the website — use the "Report Issue" link on any script page to request changes. Do not submit metadata changes via repo files.
JSON files in json/ define script properties used by the website. See existing files for structure reference.
Keep PRs small and focused. One fix or feature per PR is ideal.
PRs with new scripts opened against ProxmoxVE will be closed — submit them to ProxmoxVED instead.
PRs that fail CI checks will not be merged.

6.2 KiB Raw Blame History