# 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

```bash
# 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

```bash
# 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

| Slug | Issue | Upstream |
| --- | --- | --- |
| apache-apisix | https://projects.knownelement.com/issues/179 | https://github.com/apache/apisix.git |
| target-goalert | https://projects.knownelement.com/issues/204 | https://github.com/target/goalert.git |
| consuldemocracy | https://projects.knownelement.com/issues/189 | https://github.com/consuldemocracy/consuldemocracy.git |
| fleetdm-fleet | https://projects.knownelement.com/issues/195 | https://github.com/fleetdm/fleet.git |
| fonoster | https://projects.knownelement.com/issues/227 | https://github.com/fonoster/fonoster.git |
| healthchecks | https://projects.knownelement.com/issues/192 | https://github.com/healthchecks/healthchecks.git |
| hyperswitch | https://projects.knownelement.com/issues/209 | https://github.com/juspay/hyperswitch |
| netbox-docker | https://projects.knownelement.com/issues/201 | https://github.com/netbox-community/netbox-docker.git |
| openboxes-docker | https://projects.knownelement.com/issues/205 | https://github.com/openboxes/openboxes-docker.git |
| openfile | https://projects.knownelement.com/issues/316 | https://github.com/openfiletax/openfile.git |
| sniperphish | https://projects.knownelement.com/issues/211 | https://github.com/GemGeorge/SniperPhish-Docker.git |
| datahub | https://projects.knownelement.com/issues/309 | https://github.com/datahub-project/datahub.git |
| easy-gate | https://projects.knownelement.com/issues/54 | https://github.com/wiredlush/easy-gate.git |
| payroll-engine | https://projects.knownelement.com/issues/208 | https://github.com/Payroll-Engine/PayrollEngine.git |
| huginn | https://projects.knownelement.com/issues/194 | https://github.com/huginn/huginn.git |
| grist | https://projects.knownelement.com/issues/191 | https://github.com/gristlabs/grist-core |
| docassemble | https://projects.knownelement.com/issues/277 | https://github.com/jhpyle/docassemble.git |
| database-gateway | https://projects.knownelement.com/issues/273 | https://github.com/kazhuravlev/database-gateway.git |
| rundeck | https://projects.knownelement.com/issues/217 | https://github.com/rundeck/rundeck.git |
| slurm | https://projects.knownelement.com/issues/222 | https://github.com/SchedMD/slurm.git |
| rathole | https://projects.knownelement.com/issues/225 | https://github.com/rathole-org/rathole.git |
| jenkins | https://projects.knownelement.com/issues/234 | https://github.com/jenkinsci/jenkins.git |
| runme | https://projects.knownelement.com/issues/322 | https://github.com/runmedev/runme.git |
| seatunnel | https://projects.knownelement.com/issues/301 | https://github.com/apache/seatunnel |
| docker-webhook | https://projects.knownelement.com/issues/271 | https://github.com/thecatlady/docker-webhook |
| inventree | https://projects.knownelement.com/issues/173 | https://github.com/inventree/InvenTree.git |
| tak-server | https://projects.knownelement.com/issues/180 | https://github.com/Cloud-RF/tak-server |
| midday | https://projects.knownelement.com/issues/178 | https://github.com/midday-ai/midday.git |
| killbill | https://projects.knownelement.com/issues/181 | https://github.com/killbill/killbill.git |
| chirpstack | https://projects.knownelement.com/issues/184 | https://github.com/chirpstack/chirpstack.git |
| craig | https://projects.knownelement.com/issues/185 | https://github.com/CraigChat/craig.git |
| elabftw | https://projects.knownelement.com/issues/188 | https://github.com/elabftw/elabftw.git |
| jamovi | https://projects.knownelement.com/issues/196 | https://github.com/jamovi/jamovi.git |
| kibot | https://projects.knownelement.com/issues/197 | https://github.com/INTI-CMNB/KiBot.git |
| resgrid | https://projects.knownelement.com/issues/214 | https://github.com/Resgrid/Core |
| reviewboard | https://projects.knownelement.com/issues/216 | https://github.com/reviewboard/reviewboard.git |
| satnogs-kaitai | https://projects.knownelement.com/issues/218 | https://gitlab.com/librespacefoundation/satnogs/docker-kaitai.git |
| satnogs-webgui | https://projects.knownelement.com/issues/218 | https://gitlab.com/librespacefoundation/satnogs/docker-satnogs-webgui.git |
| sdrangel | https://projects.knownelement.com/issues/219 | https://github.com/f4exb/sdrangel-docker |
| signoz | https://projects.knownelement.com/issues/221 | https://github.com/SigNoz/signoz.git |
| warp | https://projects.knownelement.com/issues/228 | https://github.com/sebo-b/warp.git |
| drawio | https://projects.knownelement.com/issues/272 | https://github.com/jgraph/docker-drawio |
| openblocks | https://projects.knownelement.com/issues/274 | https://github.com/openblocks-dev/openblocks.git |
| wireviz-web | https://projects.knownelement.com/issues/276 | https://github.com/wireviz/wireviz-web.git |
| autobom | https://projects.knownelement.com/issues/278 | https://github.com/opulo-inc/autobom.git |
| plmore | https://projects.knownelement.com/issues/279 | https://github.com/PLMore/PLMore |
| manyfold | https://projects.knownelement.com/issues/282 | https://github.com/manyfold3d/manyfold.git |
| langfuse | https://projects.knownelement.com/issues/283 | https://github.com/langfuse/oss-llmops-stack.git |
| puter | https://projects.knownelement.com/issues/286 | https://github.com/HeyPuter/puter.git |
| windmill | https://projects.knownelement.com/issues/285 | https://github.com/windmill-labs/windmill.git |
| swupdate | https://projects.knownelement.com/issues/326 | https://github.com/sbabic/swupdate.git |
| mender-server | https://projects.knownelement.com/issues/300 | https://github.com/mendersoftware/mender-server.git |
| wireflow | https://projects.knownelement.com/issues/50 | https://github.com/vanila-io/wireflow.git |
| nautilus-trader | https://projects.knownelement.com/issues/226 | https://github.com/nautechsystems/nautilus_trader.git |
| mirlo | TBD | https://github.com/funmusicplace/mirlo.git |

All entries are initially marked as `todo`; update individual READMEs as progress is made.


## Local Verification

Run quality checks via the devtools wrapper:

```bash
# 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:

```bash
./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.