Skip to main content

Packaging

Overview​

Cloudron apps are packaged as Docker images with a specific structure that integrates with the platform's addon system, readonly filesystem, and backup/restore lifecycle. This section covers packaging, building, and publishing apps for Cloudron.

Getting started​

These documents provide a recommended reading order:

  1. Tutorial — A step-by-step walkthrough for running an app on Cloudron. Covers installing the CLI, building a Docker image, installing the app, viewing logs, and updating.

  2. Cheat sheet — Cloudron-specific considerations for writing the Dockerfile and start script. Covers the readonly filesystem, writable directories (/tmp, /run, /app/data), environment variables, process management, memory limits, signal handling, and stack-specific patterns for Apache, Nginx, PHP, and Java.

  3. Manifest — Reference for CloudronManifest.json. This file declares the app's metadata, port bindings, and addon requirements.

  4. Addons — Platform services (databases, caching, email, authentication) that apps can opt into. Covers provisioning, environment variables, and usage guidelines.

Building​

Three methods are available for building the Docker image:

  • On the server (recommended) — cloudron install and cloudron update upload the source and build directly on the server. No local Docker installation required.
  • Locally — Build with docker build and push to a registry, then install with cloudron install --image <image>. The cloudron build command automates the tag-build-push cycle.
  • Build service — Use the Docker Builder App on a separate server to offload CPU and network-intensive builds.

See the Tutorial for the default workflow and Alternative build methods for the other options.

Publishing​

Working apps can be distributed to others using a CloudronVersions.json file:

  • Publishing — How to create a version catalog, manage releases, and share the app with the community.

Reference​

  • CLI — Command reference for the cloudron CLI tool used throughout the packaging workflow (build, install, update, logs, exec, debug, and more).

Examples​

All published Cloudron apps are open source and available at git.cloudron.io/cloudron. Browse by framework:

PHP · Node · Python · Ruby/Rails · Java · Go · Rust

AI agent skills​

Agent Skills for Cursor and other AI-assisted editors teach the assistant how to package, publish, and manage Cloudron apps.

# All skills
npx skills add https://git.cloudron.io/docs/skills.git

# Individual skills
npx skills add https://git.cloudron.io/docs/skills.git --skill cloudron-app-packaging
npx skills add https://git.cloudron.io/docs/skills.git --skill cloudron-app-publishing
npx skills add https://git.cloudron.io/docs/skills.git --skill cloudron-server-ops

Getting help​

Ask questions in the App Packaging & Development category of the forum. Check the pinned topics for answers to common questions.