KNEL Cloudron Packages
This repository scaffolds Cloudron packages for Known Element's portfolio. It provides:
- A reusable application template (
templates/cloudron-app) matching Cloudron packaging conventions. - Automation helpers in
scripts/to instantiate per-app scaffolds and run builds inside a dedicated Docker container. - A curated catalog (
apps/catalog.json) that maps Known Element issue IDs to upstream projects. - Documentation under
docs/to guide packaging, testing, and release workflows.
Quick start
# Build or refresh the devtools image (first run builds automatically)
./run/dev.sh python --version
# Generate or refresh a single app scaffold
./run/dev.sh python scripts/new_app.py --slug apache-apisix
# Regenerate every scaffold (overwrites existing directories)
./run/dev.sh python scripts/new_app.py --force
# Lint an app and fail on placeholders
./run/dev.sh python scripts/lint_repo.py --slug apache-apisix --strict
# Update the status dashboard
./run/dev.sh python scripts/generate_status.py --preserve-timestamp
Packaging shell
# Build the Cloudron packager image (run when Dockerfile changes)
BUILD=1 ./run/packager.sh
# Launch an interactive Cloudron packaging shell
./run/packager.sh
All other development tasks should also use ./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
apps/– generated app scaffolds and metadatadocs/– playbooks and architecture notesdocs/CI_CD_GITEA.md– instructions for running CI/CD and publishing images via the Gitea instancedocker/devtools/– Docker image that runs scaffolding, linting, and status toolingdocker/packager/– Docker image for Cloudron packaging workflowsscripts/– helper scripts (scaffolding, tooling entrypoints)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
./run/dev.sh python scripts/lint_repo.py --slug apache-apisix --strict
# Refresh docs/APP_STATUS.md without changing the existing timestamp
./run/dev.sh python scripts/generate_status.py --preserve-timestamp
Use ./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:
./run/dev.sh python scripts/lint_repo.py --strict --slug apache-apisix
./run/dev.sh python scripts/generate_status.py --preserve-timestamp
BUILD=1 ./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 docs/PACKAGING_GUIDE.md and AGENTS.md for detailed operating procedures.