KNELCloudronPackages/docs/PACKAGING_GUIDE.md

Cloudron Packaging Playbook

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

Reference workflow

1. Build or refresh the devtools image when dependencies change:

   ./run/dev.sh python --version
   

2. Enter an interactive devtools shell so every command runs inside Docker:

   ./run/dev.sh bash --login
   

3. Implement application-specific build steps in apps/<slug>/Dockerfile and configure runtime behaviour through start.sh.
4. Update CloudronManifest.json with accurate metadata, addons, ports, and health checks.
5. Build and test using the devtools shell or one-off wrappers.
6. Push new images via the Cloudron packager shell when smoke tests pass.

Cloudron packaging essentials

• Base image: The runtime stage must derive from cloudron/base:<version>; use a dedicated builder stage to compile artefacts and copy only what you need.
• CloudronManifest: Declare metadata, exposed ports, resource limits, addons, and health checks. Keep id stable and set realistic limits per app.
• Start script: Render configuration from environment variables and launch the primary process as cloudron.
• Tests: Provide smoke tests in test/ so cloudron build --test can validate deployments.
• Updates: Bump the manifest version, document the change in changelog, and rebuild for upstream releases.

Repository linting

Run lint checks entirely through the devtools wrapper:

./run/dev.sh python scripts/lint_repo.py --slug apache-apisix --strict

Add --base-prefix if you intentionally change the final base image prefix.

Common workflows

Interactive session (recommended while iterating):

./run/dev.sh bash --login

# inside the container
python scripts/new_app.py --slug apache-apisix
python scripts/new_app.py --force
python scripts/lint_repo.py --slug apache-apisix --strict
python scripts/generate_status.py --preserve-timestamp

Non-interactive equivalents:

./run/dev.sh python scripts/new_app.py --slug apache-apisix
./run/dev.sh python scripts/new_app.py --force
./run/dev.sh python scripts/lint_repo.py --slug apache-apisix --strict
./run/dev.sh python scripts/generate_status.py --preserve-timestamp

Using the packager container

Open the Cloudron packaging environment via:

./run/packager.sh

Pass BUILD=1 to rebuild the image before launching (BUILD=1 ./run/packager.sh). Use this shell for cloudron build, cloudron install, and cloudron push operations.

Adding a new application

Generate scaffolds with the devtools wrapper:

./run/dev.sh python scripts/new_app.py --force           # regenerate entire catalog
./run/dev.sh python scripts/new_app.py --slug apache-apisix

Each scaffold contains:

• Dockerfile – multi-stage 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 app-specific details, add 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).