Community Scripts Rules

Community Scripts Rules

Use this skill before changing, testing, or submitting Community Scripts work.

Official Sources

Always verify current rules from official sources before coding or opening a PR:

• https://community-scripts.org/docs
• https://community-scripts.org/docs/contribution
• https://community-scripts.org/docs/dev_mode
• https://github.com/community-scripts/ProxmoxVED
• https://github.com/community-scripts/ProxmoxVED/blob/main/.github/pull_request_template.md
• https://github.com/community-scripts/ProxmoxVED/blob/main/AGENTS.md
• https://github.com/community-scripts/ProxmoxVED/blob/main/.github/agents/pve-script-creator.agent.md
• https://github.com/community-scripts/ProxmoxVE/blob/main/CONTRIBUTING.md

Prefer raw GitHub URLs when fetching markdown:

• https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/.github/pull_request_template.md
• https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/AGENTS.md
• https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/.github/agents/pve-script-creator.agent.md
• https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/CONTRIBUTING.md

If official sources conflict, use ProxmoxVED rules for new scripts and ProxmoxVE rules for fixes to existing promoted scripts.

Repository Routing

• New scripts go to community-scripts/ProxmoxVED.
• Existing script fixes, improvements, and features go to community-scripts/ProxmoxVE.
• Do not open new-script PRs directly against ProxmoxVE; they are closed without review.
• Keep PRs small and focused.

Mandatory ProxmoxVED Rules

For new ProxmoxVED application scripts:

• Create exactly three files: ct/<app>.sh, install/<app>-install.sh, and json/<app>.json.
• CT scripts source misc/build.func (or build.func).
• Install scripts source $FUNCTIONS_FILE_PATH.
• CT scripts declare all required var_* values, including var_arm64.
• CT scripts implement update_script().
• CT scripts end with start, build_container, description, and the standard access footer.
• Install scripts call color, verb_ip6, catch_errors, setting_up_container, network_check, and update_os.
• Install scripts end with motd_ssh, customize, and cleanup_lxc.
• Prefer bare-metal installation; never use Docker for installation scripts.
• Use helper functions instead of custom implementations.

Required Helpers

Always use project helpers instead of custom implementations:

Source Deploy & Release Fetchers

• fetch_and_deploy_gh_release "<app>" "owner/repo" "<mode>" ["latest"] ["/opt/<app>"] ["<asset-pattern>"]
  • GitHub releases. Modes: tarball (source), binary (.deb), prebuild (prebuilt archive), singlefile (single binary).
  • The resolved version is written to ~/.<app> (read back with cat ~/.<app> when needed at build/runtime).
• fetch_and_deploy_gl_release / fetch_and_deploy_gl_tag
  • GitLab (self-hosted or gitlab.com).
  • Set GITLAB_URL="https://gitlab.example.org" (default https://gitlab.com) and optional GITLAB_TOKEN.
  • Same modes as GitHub helper. Do not use GitHub helper for GitLab repositories.
• fetch_and_deploy_codeberg_release
  • Codeberg releases.
• fetch_and_deploy_from_url
  • Fallback for fixed URLs when no release API fits (avoids hand-rolled curl/tar).
• Multi-arch asset resolution:
  • Build asset patterns with arch_resolve "x86_64" "arm64" instead of hardcoding architecture strings.

Update Checks

• check_for_gh_release "<app>" "owner/repo" (returns 0 when newer release exists).
• check_for_gl_release (with GITLAB_URL).
• get_latest_github_release "owner/repo" (returns latest release version string).

Runtimes

• NODE_VERSION="22" NODE_MODULE="pnpm@x" setup_nodejs
• setup_go (no argument = latest; never pin a bare 1.23 — requires full 1.23.x)
• RUST_CRATES="..." setup_rust
• UV_PYTHON="3.12" setup_uv
• RUBY_VERSION setup_ruby
• JAVA_VERSION setup_java
• PHP_VERSION="8.3" PHP_MODULE="gd,intl,mysql" PHP_FPM="YES" setup_php (note singular PHP_MODULE)

Databases

• setup_postgresql + PG_DB_NAME PG_DB_USER PG_DB_EXTENSIONS="vector,pg_stat_statements" [PG_DB_GRANT_SUPERUSER="true"] setup_postgresql_db
  • List every extension enabled by app schema. Non-trusted extensions need pre-creating. Grant superuser only if strictly needed.
• setup_mariadb + setup_mariadb_db
• setup_mysql + setup_mysql_db
• setup_mongodb
• setup_clickhouse
• setup_meilisearch

Tools & Infrastructure

• setup_composer
• setup_ffmpeg
• setup_imagemagick
• setup_gs
• setup_yq
• setup_adminer
• setup_hwaccel
• setup_nltk

Repositories, Services, Dependencies & TLS

• setup_deb822_repo "name" "<gpg_url>" "<repo_url>" "<suite>" ["component"] ["archs"] for 3rd-party APT repositories (never hand-roll GPG keys or sources.list files).
• safe_service_restart <svc>
• ensure_dependencies <pkg...> (installs jq, openssl, etc. on demand).
• install_packages_with_retry <pkg...>
• create_self_signed_cert "<app>" -> /etc/ssl/<app>/<app>.{crt,key} (SAN covers hostname + container IP + localhost; never hand-roll openssl).

Data Persistence & Updates (Critical)

CLEAN_INSTALL=1 fetch_and_deploy_* wipes /opt/<app> before re-extracting. Any user state or secrets stored inside /opt/<app> will be permanently lost during updates.

Follow these strict rules:

1. Standard Pattern (Preferred):

   • Store all persistent state and data outside the app directory in /opt/<app>_data (NOT /opt/<app>/data).
   • Point the application there via its data directory configuration or environment variables (e.g. DATA_DIR, *_DATA_DIR).
   • Place non-regenerable configuration and secrets (signing keys, generated .env, .toml) in /opt/<app>_data as well.
   • Updates keep everything with no backup or restore step required.

2. Exception Pattern (Manifest Backup Helpers):

   • Only when data genuinely cannot be relocated outside /opt/<app>, back it up in update_script() using the manifest helpers (never use manual cp or /tmp):

     create_backup /opt/<app>/data /opt/<app>/.env
     CLEAN_INSTALL=1 fetch_and_deploy_gh_release ...
     restore_backup
     

   • create_backup copies paths into /opt/<NSAPP>.backup with a manifest, is idempotent, and aborts update on failure.
   • restore_backup restores every manifest path and removes the backup store.
   • Override default backup store location with BACKUP_DIR if /opt/<NSAPP>.backup clashes.

3. Never back up to /tmp (temporary directories can be cleared by the system).

Secure-Context Web Apps (HTTPS)

Modern browser APIs such as crypto.subtle (Web Crypto / PKCE), navigator.storage.getDirectory (OPFS), service workers, and SharedArrayBuffer require a secure context (HTTPS or localhost). Applications using them break over plain http://<IP> with errors like crypto.subtle is unavailable in insecure contexts.

When an application requires a secure context:

• Terminate TLS with create_self_signed_cert "<app>" behind an Nginx reverse proxy listening on port 443 with SSL enabled.
• Redirect port 80 to port 443.
• Proxy requests to the application on its internal port (or serve static files directly).
• If the application source uses SharedArrayBuffer, configure cross-origin isolation headers on the HTTPS server:
  • add_header Cross-Origin-Opener-Policy same-origin always;
  • add_header Cross-Origin-Embedder-Policy require-corp always;
• In json/<app>.json notes, instruct users to accept the self-signed certificate in their browser and access the application via https://.

Anti-Patterns

Never do these unless official rules explicitly change:

• Do not wrap setup_*, fetch_and_deploy_*, or check_for_* in msg_info / msg_ok blocks (they have built-in logging).
• Do not use Docker for ProxmoxVED install scripts.
• Do not implement custom download logic when a helper exists.
• Do not implement custom version checks when check_for_* helpers apply.
• Do not create pointless variables such as APP_DIR, APP_USER, or APP_PORT.
• Do not use sudo.
• Do not use apt-get; use apt.
• Do not list pre-installed core packages as dependencies: curl, sudo, wget, gnupg, ca-certificates, jq, mc.
• Do not hardcode credentials, secrets, or versions for external tools.
• Do not back up to /tmp; use /opt.
• Do not use echo, printf, or tee for file creation; use heredocs.
• Do not create external shell scripts, custom credentials files, or unnecessary system users.
• Do not use export in .env files.
• Do not add systemctl daemon-reload for new services unless current rules require it.
• Do not add (Patience) in message labels.
• Prefix package (apt), npm, and build commands with $STD.

JSON Metadata

For json/<app>.json, include all required fields:

• Required fields:
  • name, slug, categories, date_created, type, updateable, privileged, architectures, interface_port
  • documentation, website, repository, logo, description
  • install_methods, default_credentials, notes
• Optional fields:
  • platforms, app_vars

Metadata Rules

• No top-level config_path: config_path belongs under individual install methods in install_methods (a script can have multiple methods with different paths).
• date_created: Today's date in YYYY-MM-DD format.
• install_methods.resources: Must match CT script variables (var_cpu, var_ram, var_disk, var_os, var_version).
• repository: Upstream repository as a full URL (e.g., https://github.com/owner/repo, https://gitlab.com/owner/repo, https://codeberg.org/owner/repo). Never bare owner/repo.
• logo: Use CDN pattern: https://cdn.jsdelivr.net/gh/selfhst/icons@main/webp/<slug>.webp.
• architectures: Replaced the deprecated has_arm boolean. It must match var_arm64 in the CT script (arch_check aborts with exit code 106 on arm64 hosts when CT script says no):

• platforms (optional): ["pve"], ["incus"] or both. Defaults to Proxmox VE if omitted. Only claim incus if script exists in the Incus repository.
• app_vars (optional): Declares variables for unattended installs. Requires matching 3-part implementation:
  1. install/<app>-install.sh (prompts only when unset):

     if [[ -z "${var_admin_user:-}" ]]; then
       read -rp "${TAB3}Admin username: " var_admin_user
     fi
     var_admin_user="${var_admin_user:-admin}"
     

  2. ct/<app>.sh (exports variable to container environment):

     export var_admin_user="${var_admin_user:-}"
     

  3. json/<app>.json (declares parameter metadata):

     "app_vars": [
       { "name": "var_admin_user", "label": "Admin Username", "type": "text", "default": "admin" },
       { "name": "var_admin_token", "label": "API Token", "type": "password", "secret": true, "required": true, "help": "The script exits when this is empty" }
     ]
     

  • Supported type values: text, password, number, boolean (emits yes/no), select (with options).
  • Mark credentials and sensitive fields with "secret": true.

Testing

Test on a real Proxmox host before PR when possible.

Useful development modes:

export dev_mode="keep,logs"
export var_verbose="yes"
bash -c "$(curl -fsSL https://raw.githubusercontent.com/<fork>/<repo>/<branch>/ct/<app>.sh)"

Use:

• logs for persistent logs under /var/log/community-scripts/.
• keep to preserve failed containers.
• motd for early SSH access.
• pause for step-by-step inspection.
• breakpoint for an interactive shell on failure.
• trace only in isolated environments because it can expose secrets.
• dryrun for simulation only.

Validate install, update path, service health, logs, credentials handling, exposed ports, and absence of hardcoded secrets.

PR Template Rules

Use the official ProxmoxVED PR template verbatim. Do not replace it with a custom body.

For new scripts, the PR must include:

• 🆕 New script checked.
• One arm64 option checked.
• All prerequisites checked only if true.
• Code and security review checkboxes checked only after self-review.
• Exactly one AI assistance option checked:
  • No AI used, or
  • AI was used.
• All Application Requirements checked only if true:
  • application is at least 6 months old;
  • actively maintained;
  • 600+ GitHub stars;
  • official release tarballs are published;
  • contributor understands not all scripts are accepted.
• Source links filled.

The automated check closes PRs missing required template sections or required checkbox selections.

Work Sequence

1. Fetch current official rules from the sources above.
2. Decide the correct repo: ProxmoxVED for new scripts, ProxmoxVE for existing promoted scripts.
3. Inspect similar existing scripts before coding.
4. Implement with official helpers and standard structure (CT, install, JSON).
5. Test with dev_mode="keep,logs" and real Proxmox evidence.
6. Run the local checklist from this skill.
7. Open PR only after checks pass.
8. If the bot closes the PR, read the bot comment exactly and fix the missing rule before opening a replacement PR.

Local Checklist

• Official sources checked this session.
• Correct target repository selected (ProxmoxVED for new, ProxmoxVE for fixes/updates).
• Exactly three files created: ct/<slug>.sh, install/<slug>-install.sh, json/<slug>.json.
• Script structure matches current templates (CT declarations, install flow, footers).
• Required helper functions used (fetch and deploy, runtimes, databases, tools).
• No wrapper msg_* calls around helpers with built-in logging.
• No anti-patterns present (no Docker, no sudo, no apt-get, $STD prefix on apt/build).
• Persistent data and configuration reside in /opt/<app>_data (or managed via create_backup / restore_backup manifest helpers).
• Backups go to /opt, never /tmp.
• Multi-arch asset patterns use arch_resolve (no hardcoded architecture tokens).
• 3rd-party APT repos use setup_deb822_repo; TLS certs use create_self_signed_cert.
• GitLab sources use fetch_and_deploy_gl_release / check_for_gl_release with GITLAB_URL.
• Secure-context web applications configured with HTTPS reverse proxy (and COOP/COEP headers if using SharedArrayBuffer).
• CT var_arm64 accurately reflects arm64 support.
• JSON metadata present and consistent with CT script resources.
• JSON architectures agrees with CT var_arm64 (yes -> ["amd64", "arm64"], no -> ["amd64"], unset -> omitted).
• JSON repository is a full URL (https://...), not bare owner/repo.
• No top-level config_path in JSON (configured on install methods).
• JSON platforms claims incus only if script exists in the Incus repository.
• Every read in install script is guarded by -z "${var_x:-}", exported in ct/<app>.sh, and declared in JSON app_vars.
• Real install test completed or limitation documented.
• update_script() reviewed or tested.
• PR body uses official template verbatim.
• AI assistance checkbox is selected when AI was used.
• Bot comment reviewed if PR was closed.