mirror of https://github.com/community-scripts/ProxmoxVE.git synced 2026-02-06 05:13:27 +01:00

Files

CanbiZ e72c7d8f7f Update contribution docs for improved workflow and clarity

Revised multiple documentation files to clarify the recommended development workflow: contributors must test scripts via curl from their GitHub fork (not local bash), use setup-fork.sh for URL rewriting, and submit only new files using cherry-pick. Expanded and modernized install and JSON metadata template guides, emphasizing use of helper functions, resource requirements, and the JSON generator tool. Added detailed step-by-step instructions, best practices, and updated examples throughout.

2026-01-18 18:18:52 +01:00

4.4 KiB

Raw Blame History

JSON Metadata Files - Quick Reference

The metadata file (config/myapp.json) tells the web interface how to display your application.

Quick Start

Use the JSON Generator Tool: https://community-scripts.github.io/ProxmoxVE/json-editor

Enter application details
Generator creates config/myapp.json
Copy the output to your contribution

File Structure

{
  "name": "MyApp",
  "slug": "myapp",
  "categories": ["utilities", "monitoring"],
  "date_created": "2025-01-15",
  "type": "ct",
  "interface_port": "3000",
  "logo": "https://example.com/logo.png",
  "config_path": "/etc/myapp/config.json",
  "description": "Brief description of what MyApp does",
  "install_methods": {
    "1": {
      "type": "ct",
      "resources": {
        "cpu": "2",
        "ram": "2048",
        "disk": "10"
      },
      "pre_install_msg": "Optional message shown before installation"
    }
  },
  "default_credentials": {
    "username": "admin",
    "password": "Generated during install"
  },
  "notes": "Optional setup notes",
  "notes_type": "markdown"
}

Field Reference

Field	Required	Example	Notes
`name`	Yes	"MyApp"	Display name
`slug`	Yes	"myapp"	URL-friendly identifier (lowercase, no spaces)
`categories`	Yes	["utilities"]	One or more from available list
`date_created`	Yes	"2025-01-15"	Format: YYYY-MM-DD
`type`	Yes	"ct"	Container type: "ct" or "vm"
`interface_port`	Yes	"3000"	Default web interface port
`logo`	No	"https://..."	Logo URL (64px x 64px PNG)
`config_path`	Yes	"/etc/myapp/config.json"	Main config file location
`description`	Yes	"App description"	Brief description (100 chars)
`install_methods`	Yes	See below	Installation resources
`default_credentials`	No	See below	Optional default login
`notes`	No	"Setup info"	Additional notes
`notes_type`	No	"markdown"	Format of notes field

Install Methods

Each installation method specifies resource requirements:

"install_methods": {
  "1": {
    "type": "ct",
    "resources": {
      "cpu": "2",
      "ram": "2048",
      "disk": "10"
    },
    "pre_install_msg": "Optional message"
  }
}

Resource Defaults:

CPU: Cores (1-8)
RAM: Megabytes (256-4096)
Disk: Gigabytes (4-50)

Best Practices

Use the JSON Generator - It validates structure
Keep descriptions short - 100 characters max
Use real resource requirements - Based on your testing
Include sensible defaults - Pre-filled in install_methods
Slug must be lowercase - No spaces, use hyphens

Reference Examples

See actual examples in the repo:

Need Help?

JSON Generator - Interactive tool
README.md - Full contribution workflow
Quick Start - Step-by-step guide

4.4 KiB Raw Blame History