JSON metadata template

json/<slug>.json describes a script for the website: name, description, resources, notes and the values a user can pass to the install. It exists only in DevScripts. A workflow, push_json_to_pocketbase.yml, copies it into the website's database. This page documents exactly what that workflow reads.

The website's JSON generator produces the file from a form and can import an existing one.

TemplateCopy Anchor Link

{
  "name": "AppName",
  "slug": "appname",
  "categories": [0],
  "date_created": "2026-01-16",
  "type": "ct",
  "updateable": true,
  "privileged": false,
  "interface_port": 3000,
  "documentation": "https://docs.appname.com/",
  "website": "https://appname.com/",
  "repository": "https://github.com/owner/appname",
  "architectures": ["amd64"],
  "platforms": ["pve"],
  "logo": "https://cdn.jsdelivr.net/gh/selfhst/icons@main/webp/appname.webp",
  "description": "What the application is and what it can do, in two or three sentences.",
  "install_methods": [
    {
      "type": "default",
      "script": "ct/appname.sh",
      "config_path": "/opt/appname/.env",
      "resources": {
        "cpu": 2,
        "ram": 2048,
        "hdd": 8,
        "os": "Debian",
        "version": "13"
      }
    }
  ],
  "default_credentials": {
    "username": null,
    "password": null
  },
  "notes": [
    {
      "text": "Create the first account in the web interface; it becomes the administrator.",
      "type": "info"
    }
  ],
  "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"
    }
  ]
}

Leave app_vars out when the install script takes no values from the user. A real file to compare with: json/temporal.json in DevScripts.

Top-level fieldsCopy Anchor Link

Always write architectures and platforms. If architectures is missing, the sync reads the var_arm64 line of the first install method's script instead: yes gives both architectures, anything else amd64 only. If platforms is missing, it stores ["pve"].

architectures describes; var_arm64 decides. The engine refuses to build on arm64 when the script says no, whatever the JSON claims. Keep them in agreement.

CategoriesCopy Anchor Link

The list is json/metadata.json in DevScripts.

Install methodsCopy Anchor Link

install_methods is stored as written. A script with one way to install has one entry.

The sync also uses script, together with install/<slug>-install.sh, to find the last commit that touched the script.

NotesCopy Anchor Link

"notes": [
  { "text": "Change the default password after first login!", "type": "warning" }
]

type is info, warning or error. Use an empty array when there is nothing to say.

• At most three notes, one or two short sentences each.
• Only what a user has to know or do: how to get the first login, a required manual step, a real risk such as an interface without authentication.
• Not what the script installs, build times, memory figures, how updates work or upstream bugs.

app_varsCopy Anchor Link

app_vars describes values the install script already reads from the environment, so the website's command generator can offer a field for each and an install can run without questions. It does not create the behaviour. The script has to read the variable and the ct/ script has to export it, see the install template.

A real example, from json/gitea-runner.json:

"app_vars": [
  {
    "name": "var_gitea_url",
    "label": "Gitea Instance URL",
    "type": "text",
    "required": false,
    "help": "URL of your Gitea instance (e.g. http://192.168.1.100:3000 or https://gitea.example.com)"
  },
  {
    "name": "var_gitea_token",
    "label": "Registration Token",
    "type": "password",
    "secret": true,
    "required": false,
    "help": "Runner registration token from Gitea (Site Administration > Actions > Runners or Repo/Org Settings > Actions > Runners)"
  }
]

The matching lines in ct/gitea-runner.sh:

export var_gitea_url="${var_gitea_url:-}"
export var_gitea_token="${var_gitea_token:-}"

Fields you leave outCopy Anchor Link

The sync fills these itself. Writing them has no effect or the wrong one:

These are owned by maintainers or by the website's own release sync. Do not add them to a new script's JSON:

Older files may contain has_arm, script_created, port, default_user, default_passwd or github. The sync still understands them; do not use them in a new file.

When the file is readCopy Anchor Link

Once the record is marked as released, the DevScripts sync skips it.