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.

Cloudron app packages are containerized applications with a separate filesystem from the host server. Understanding how packages work helps you customize and manage your apps effectively.

Package architecture​

Read-only filesystem​

App packages run in a read-only filesystem and cannot be modified. This ensures consistency and security across updates and restarts.

Only these directories are writable:

  • /app/data - Persistent app data (survives restarts and updates)
  • /run - Runtime files (temporary, cleared on restart)
  • /tmp - Temporary files (cleared on restart)

Database access​

Apps have access to databases through addons. Databases are provisioned automatically and accessed via environment variables like CLOUDRON_POSTGRESQL_HOST, CLOUDRON_MYSQL_USERNAME, etc.

Making changes​

File Manager​

Use the File Manager to edit files in /app/data directly from your web browser.

Web terminal​

The Web terminal provides access to the full filesystem and includes buttons at the top to quickly access app databases.

Customization approach​

Customization differs per app. Individual package documentation provides specific guidance on what can be changed and how.

For example, the SFTPGo app has a /app/data/sftpgo.json file where users can add custom configuration.

Important restrictions​

Certain settings are managed automatically and should not be changed:

Database configuration​

Database settings (host, port, username, password) are always managed and overwritten on every app restart. These settings should never be changed manually.

Example from SFTPGo start.sh:

Bash
# PostgreSQL settings - automatically configured on every restart
yq -i -o json '.data_provider.driver="postgresql"' $config_file
yq -i -o json '.data_provider.name=strenv(CLOUDRON_POSTGRESQL_DATABASE)' $config_file
yq -i -o json '.data_provider.host=strenv(CLOUDRON_POSTGRESQL_HOST)' $config_file

Domains and ports​

Domain names and port numbers are dynamic and patched automatically based on the app's deployment location. These should not be changed.

Email configuration​

Email settings are managed automatically. By default, apps are configured to use the built-in mail server. Some packages have an option to disable email autoconfiguration if you need to configure email delivery manually.

SSO authentication​

User authentication settings related to SSO configuration (hostname, port, username, password) are managed automatically and should not be changed.

Troubleshooting​

If a configuration file resets on its own after editing, the setting is likely managed automatically. Check the app's startup script in the package repository to confirm which settings are overwritten on restart.

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, 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​

cloudron install and cloudron update upload the source and build the image on the server. No local Docker installation is required. See the Tutorial.

To persist built images, build on the local machine and install with --image. See Building locally.

Publishing​

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

  • Publishing - How to create a version catalog, manage releases, optionally list on Community Apps, and share the app with others.

Reference​

  • Versions - Reference for CloudronVersions.json.
  • CLI - Command reference for the cloudron CLI tool used throughout the packaging workflow (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.