cloudron-app-publishing

Cloudron App Publishing

Distribute Cloudron apps independently using a CloudronVersions.json version catalog. Users add the file's URL in their dashboard or install via cloudron install --versions-url <url>.

Quick Reference

• Docs: docs.cloudron.io/packaging/publishing
• Upstream skill: git.cloudron.io/docs/skills (cloudron-app-publishing)
• Prerequisite: App must be built with cloudron build (local or build service) — on-server builds cannot be published
• Key file: CloudronVersions.json — version catalog hosted at a public URL
• Listing: Cloudron Community Apps accepts a public versions URL after the catalog contains a tested release; listing is optional
• Forum: App Packaging & Development

Workflow

cloudron versions init  # creates CloudronVersions.json + DESCRIPTION.md, CHANGELOG, POSTINSTALL.md (edit all placeholders)
cloudron build          # build and push image (first run prompts for Docker repository, e.g. registry/username/myapp)
cloudron versions add --state testing  # add the registry image without exposing it as stable
cloudron versions update --version=1.0.0 --state=published
# host CloudronVersions.json at a public URL

cloudron versions init also adds missing publishing fields to CloudronManifest.json with placeholder values. Edit all placeholders and scaffolded files before adding a version.

Repository Baseline

Commit these before the first registry build:

• CloudronVersions.json initialized as { "stable": true, "versions": {} }; never fabricate an entry before cloudron build records a real registry image.
• CloudronManifest.json publishing metadata: id, title, author, description, tagline, version, website, contactEmail, iconUrl, packagerName, packagerUrl, non-empty tags, non-empty mediaLinks, changelog, and minBoxVersion of at least 9.1.0. Add packageUrl when the listing must link to the package source repository; this requires minBoxVersion 10.0.0.
• A local square 256×256 PNG icon (icon normally points to it) and at least one privacy-reviewed product screenshot or hero. mediaLinks must use public HTTPS URLs; Cloudron recommends 3:1 images such as 1200×400.
• A Cloudron-format changelog file when using file://: each release heading must be exactly [X.Y.Z], because cloudron versions add does not parse Keep a Changelog headings such as ## [X.Y.Z].
• A short publishing runbook that records the canonical catalog URL, registry/repository ownership, asset provenance, test install, rollback, and Community Apps listing steps without storing credentials.
• A managed GitHub Actions release workflow that creates and verifies keyless provenance for the immutable image digest and exact generated CloudronVersions.json; use reference/release-artifact-provenance.md before the first publication.