Cloudron Packaging Playbook

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

Reference workflow

Build or refresh the devtools image when dependencies change:
```
./output/run/dev.sh python --version
```
Enter an interactive devtools shell so every command runs inside Docker:
```
./output/run/dev.sh bash --login
```
Implement application-specific build steps in output/apps/<slug>/Dockerfile and configure runtime behaviour through start.sh.
Update CloudronManifest.json with accurate metadata, addons, ports, and health checks.
Build and test using the devtools shell or one-off wrappers.
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:

./output/run/dev.sh python output/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):

./output/run/dev.sh bash --login

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

Non-interactive equivalents:

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

Using the packager container

Open the Cloudron packaging environment via:

./output/run/packager.sh

Pass BUILD=1 to rebuild the image before launching (BUILD=1 ./output/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:

./output/run/dev.sh python output/scripts/new_app.py --force           # regenerate entire catalog
./output/run/dev.sh python output/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 output/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