Cloudron Packaging Playbook

This repository standardises the workflow for building and maintaining Cloudron packages for the Known Element portfolio.

Reference workflow

Generate a package scaffold from the shared template using scripts/new_app.py.
Run all build, test, and release tasks inside the docker/packager container to avoid host pollution.
Implement application-specific build steps in apps/<slug>/Dockerfile and configure the runtime via start.sh.
Update CloudronManifest.json with accurate metadata, addons, ports, and health checks based on the upstream project.
Build and test locally with the Cloudron CLI (cloudron build, cloudron install --app <domain>) inside the packaging container.
Push the image to the Cloudron registry (cloudron push) and publish once happy with smoke-test coverage.

Cloudron packaging essentials

Base image: Start from cloudron/base:<version> and add only the dependencies the app requires.
CloudronManifest: The manifest declares metadata, exposed ports, resource limits, addons (databases, object storage, email), and health checks. Always keep the id stable since it uniquely identifies the package inside Cloudron ecosystems.
Start script: Use start.sh to render configuration from environment variables and launch the primary process under the cloudron user.
Tests: Provide smoke tests in test/ that Cloudron can run via cloudron build --test.
Updates: Bump the manifest version, document the change in changelog, and rebuild when upstream releases.

Repository linting

Run the scaffold lint checks after editing an app to catch placeholder artefacts:

python3 scripts/lint_repo.py

Set CLOUDRON_BASE to override the expected base image version when needed.

Use the Makefile shortcuts for common tasks:

make scaffold   # regenerate scaffolds from catalog
make lint       # run repo lint checks
make status     # refresh docs/APP_STATUS.md

Leverage the Gitea Actions workflow (.gitea/workflows/ci.yml) to enforce make lint and status generation on every push; instructions for runner setup live in docs/CI_CD_GITEA.md.

Run the local harness via ./scripts/ci_local.sh (or make ci-local) to replicate the CI pipeline without relying on a remote runner; see docs/LOCAL_TESTING.md for hook integration.

Using the packager container

# Build the helper image
BUILD=1 scripts/run_packager.sh

# Launch an interactive shell inside the packaging environment
scripts/run_packager.sh

The container bundles the Cloudron CLI, Docker CLI, git, curl, and other tooling for reproducible builds. The host Docker socket is mounted so you can reuse local credentials while keeping the host clean.

Adding a new application

# Create the full scaffold for all catalog entries
python3 scripts/new_app.py

# Or generate a single skeleton
python3 scripts/new_app.py --slug apache-apisix

Each scaffold contains:

Dockerfile – build instructions
start.sh – runtime entrypoint
CloudronManifest.json – metadata and permissions
test/smoke.sh – placeholder smoke test
metadata.json – issue and upstream bookkeeping
README.md – packaging checklist

Update these files with the app-specific details, add upstream artefacts under app/, and commit the changes.

Repository etiquette

Document design decisions and manual steps in docs/ or the per-app README.
Keep automation scripts idempotent; rerunning them should not damage uncommitted work.
Use semantic versioning in manifest files (MAJOR.MINOR.PATCH).

3.6 KiB Raw Blame History Unescape Escape