Skip to main content

Publishing

Overview​

CloudronVersions.json is a version catalog that enables distributing apps independently. Host this file at a URL and share it with others. Users who add the URL in their dashboard receive version updates automatically.

Prerequisites​

The app must be built and pushed to a registry using cloudron build (either locally or via a build service). On-server builds do not produce registry-hosted images and cannot be used with CloudronVersions.json.

Initialize​

Create the versions file in the package directory:

# create the versions file and add missing fields in manifest
cloudron versions init
Created CloudronVersions.json.

Added missing fields to CloudronManifest.json: id, title, author, ...
Created stub files: DESCRIPTION.md, CHANGELOG, POSTINSTALL.md

Edit the following fields in CloudronManifest.json before publishing:
  id, title, author, tagline, website, contactEmail, iconUrl, packagerName, packagerUrl
  tags, mediaLinks, DESCRIPTION.md, CHANGELOG, POSTINSTALL.md

Use "cloudron versions add" to add a version.

Publishing requires additional manifest fields beyond what cloudron init provides (see the Manifest reference for the full list). cloudron versions init adds any missing fields to CloudronManifest.json with placeholder values and creates stub files (DESCRIPTION.md, CHANGELOG, POSTINSTALL.md). Edit the placeholders and stub files before adding a version.

Add a version​

After building with cloudron build, add the current version to the catalog. cloudron versions add reads the version from CloudronManifest.json and the last built Docker image, then creates an entry in CloudronVersions.json.

Update a version​

warning

Avoid changing the manifest or image of a published version. Users may have already installed it. To ship changes, revoke the existing version and add a new one.

cloudron versions update --version 1.0.0
Updated 1.0.0 in CloudronVersions.json

Revoke a version​

Revoke the latest published version if it has a critical issue. Users who have not yet updated will not receive it:

cloudron versions revoke
Marked 1.0.0 as revoked in CloudronVersions.json

To ship a fix, bump the version in CloudronManifest.json, rebuild, and run cloudron versions add.

Distribute​

Host the CloudronVersions.json file at a publicly accessible URL. Any static file host, git repository, or web server works.

Users can install the app in two ways:

  • Dashboard — Add the CloudronVersions.json URL under Community apps in the dashboard. Updates appear automatically.
  • CLI — Install directly with cloudron install --versions-url <url>.

Spread the word​

Post about new packages in the Community Apps category of the forum.