9.2 KiB
KNEL Cloudron Packages
This repository scaffolds Cloudron packages for Known Element's portfolio. It provides:
- A reusable application template (
output/templates/cloudron-app) matching Cloudron packaging conventions. - Automation helpers in
output/scripts/to instantiate per-app scaffolds and run builds inside a dedicated Docker container. - A curated catalog (
output/apps/catalog.json) that maps Known Element issue IDs to upstream projects. - Documentation under
output/docs/to guide packaging, testing, and release workflows.
Quick start
# Build or refresh the devtools image (first run builds automatically)
./output/run/dev.sh python --version
# Generate or refresh a single app scaffold
./output/run/dev.sh python output/scripts/new_app.py --slug apache-apisix
# Regenerate every scaffold (overwrites existing directories)
./output/run/dev.sh python output/scripts/new_app.py --force
# Lint an app and fail on placeholders
./output/run/dev.sh python output/scripts/lint_repo.py --slug apache-apisix --strict
# Update the status dashboard
./output/run/dev.sh python output/scripts/generate_status.py --preserve-timestamp
Packaging shell
# Build the Cloudron packager image (run when Dockerfile changes)
BUILD=1 ./output/run/packager.sh
# Launch an interactive Cloudron packaging shell
./output/run/packager.sh
All other development tasks should also use ./output/run/dev.sh (pass the desired command after the script). The wrapper will build the devtools image if needed and ensure every command executes inside Docker.
Repository layout
collab/– shared workspace for operator/agent collaboration (questions, proposals, plans).output/apps/– generated Cloudron app scaffolds and metadata.output/docs/– playbooks, architecture notes, and status dashboards.output/docker/devtools/– Docker image that runs scaffolding, linting, and status tooling.output/docker/packager/– Docker image for Cloudron packaging workflows.output/run/– wrapper scripts for devtools and packager containers.output/scripts/– helper scripts (scaffolding, tooling entrypoints).output/templates/– base Cloudron app template.
Application catalog
All entries are initially marked as todo; update individual READMEs as progress is made.
Local Verification
Run quality checks via the devtools wrapper:
# Fail if placeholders remain in the target manifest/start script
./output/run/dev.sh python output/scripts/lint_repo.py --slug apache-apisix --strict
# Refresh output/docs/APP_STATUS.md without changing the existing timestamp
./output/run/dev.sh python output/scripts/generate_status.py --preserve-timestamp
Use ./output/run/packager.sh whenever you need the Cloudron CLI to build, install, or push packages—it drops you into the dedicated packaging container.
CI/CD
The workflow .gitea/workflows/ci.yml mirrors the same commands by invoking the devtools container inside the runner. To reproduce the pipeline locally, run:
./output/run/dev.sh python output/scripts/lint_repo.py --strict --slug apache-apisix
./output/run/dev.sh python output/scripts/generate_status.py --preserve-timestamp
BUILD=1 ./output/run/packager.sh # optional: rebuild packager image before smoke tests
Once a Gitea Actions runner is available, enable the workflow and it will build knel/cloudron-devtools/knel/cloudron-ci automatically.
Refer to output/docs/PACKAGING_GUIDE.md and AGENTS.md for detailed operating procedures.