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. See the Versions reference for the file format.

Prerequisites​

Each published version needs a Docker image in a registry. On-server builds from cloudron install do not produce a registry-hosted image and cannot be used with CloudronVersions.json.

cloudron versions add uses the last cloudron builder image (see Using a container registry). On a terminal it asks for confirmation. Pass --last-build to skip the prompt, or --image to record a specific image:

cloudron versions add
cloudron versions add --last-build
cloudron versions add --image registry.example.com/username/myapp:1.0.0

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, ...
Created stub files: DESCRIPTION.md, CHANGELOG, POSTINSTALL.md

Edit the following fields in CloudronManifest.json before publishing:
  id, title, tagline, website, iconUrl, packageUrl, 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​

cloudron versions add reads the version from CloudronManifest.json and records a registry Docker image in CloudronVersions.json. The image comes from --image, or from the last cloudron builder build.

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 and run cloudron versions add (or pass --image / --last-build).

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.

Optionally, list your app on Community Apps so others can browse it and copy the install URL. Listing is not required. Sharing the URL directly works just as well.