Cloudron Packaging Difficulty Scorer

Step 1: Find the dependency map. Look for a docker-compose.yml in the app's repo. This is the single most valuable file. Each service that is not postgres, mysql, redis, mongodb, or memcached is a process you need to manage. Count them.

Step 2: Identify the runtime. Look at the root of the repo for telltale files: package.json (Node.js), requirements.txt or pyproject.toml (Python), composer.json (PHP), go.mod (Go), Cargo.toml (Rust), Gemfile (Ruby), pom.xml or build.gradle (Java). The Cloudron base image (5.0.0) has Node 24, Python 3.12, and PHP 8.3. Everything else needs installing.

Step 3: Map databases to addons. Cloudron provides: PostgreSQL 16, MySQL 8, MongoDB 7, Redis 8 as managed addons. If the app uses one of these, it is free. If it needs Elasticsearch, Meilisearch, Qdrant, ClickHouse, or similar, that must run inside your container.

Step 4: Check for message brokers. Search the compose file and code for references to RabbitMQ, AMQP, Celery, Sidekiq, Bull, BullMQ. If the app uses Celery or Bull, check whether it supports Redis as a broker backend (most do). If it requires full AMQP, you will need LavinMQ inside the container.

Step 5: Estimate filesystem writes. This is hardest to assess without running the app. Look at the Dockerfile's VOLUME declarations and any symlink setup. Apps that write only to a single data directory are simple. Apps that scatter writes across /etc, /var, and their own install directory are painful.

Step 6: Check authentication. Search the docs for "LDAP", "OIDC", "OpenID", "SAML", "SSO". If any are supported natively, Cloudron integration is easy. If the app only supports its own user system, check whether the first admin can be seeded via environment variables or CLI command.

Scoring: 0 to 2 = Trivial (hours). 3 to 4 = Easy (a day). 5 to 6 = Medium (days). 7 to 9 = Hard (weeks). 10+ = Impractical (rethink).

Bonus modifiers (adjust your score)

The six axes capture the structural complexity. But real packaging difficulty also depends on factors that are harder to score mechanically. Consider these modifiers after calculating your base score.

Upstream project maturity (+0 to +2). Is the project on a stable release with semantic versioning and a clear upgrade path? Or is it a fast-moving alpha where the config format changes every week? Rapidly evolving projects mean your package will break frequently and need constant maintenance. A project tagged "v0.1" with daily breaking changes deserves +1 or +2.

Configuration surface area (+0 to +1). An app with 5 environment variables is straightforward to wire up in start.sh. An app with 80+ config options, many of which interact, means a complex config generation step and more things to get wrong. Heavily configurable apps like GitLab or Nextcloud deserve +1.

Media and large file handling (+0 to +2). Does the app transcode video, process large uploads, or download ML models at startup? These create memory pressure (Cloudron's 256 MB default is insufficient), slow boot times (health check timeouts), and large /app/data volumes. Immich and AVideo are examples. Add +1 for heavy media processing, +2 if it involves ML model downloads.

Network requirements beyond HTTP (+0 to +2). Cloudron's reverse proxy handles HTTP/HTTPS and WebSocket. If the app needs raw UDP ports (VoIP, DNS, game servers), custom TCP ports, multicast, or specific firewall rules, packaging becomes significantly harder. Jitsi's JVB needing UDP port ranges is the classic example. Add +1 for non-HTTP TCP, +2 for UDP or multicast.

External API dependencies (+0 to +1). Does the app require third-party API keys to function at all (not just for optional features)? FacilMap needs map tile API keys. AI apps need LLM provider keys. This does not make packaging harder technically, but it means the app is not "instantly usable after install" as Cloudron expects. Document these requirements clearly in POSTINSTALL.md. Add +1 if the app is non-functional without external API configuration.

Upstream Docker image compatibility (+0 to +2). Is the upstream image Alpine-based with musl libc? If so, binaries compiled inside it will not run on Cloudron's Ubuntu/glibc base image. The n8n package recently hit this: copying from an Alpine upstream produced "libc.musl-x86_64.so.1: cannot open shared object file" errors on Cloudron. If you need to use a multi-stage build from an Alpine upstream, add +1. If the upstream has hardcoded assumptions about its own init system (like docassemble's supervisord and initialize.sh), add +2.

Maintenance burden (ongoing). This is not a one-time score but worth noting: apps with frequent releases, plugin ecosystems, or database migrations on every update will need ongoing attention. A trivially packaged app that releases weekly is more work over its lifetime than a hard-packaged app that releases quarterly.