# 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

```bash
# Generate all app scaffolds from the catalog
python3 scripts/new_app.py

# Or regenerate scaffolds via Makefile
make scaffold

# Work on a single app skeleton
python3 scripts/new_app.py --slug apache-apisix

# Update the status table
make status

# Lint generated apps
make lint

# Run the full CI harness locally
make ci-local

# Build and enter the Cloudron packager container
BUILD=1 scripts/run_packager.sh
scripts/run_packager.sh
```

Within the container, use the Cloudron CLI to build, test, and publish packages without touching the host environment:

```bash
cloudron login my.example.cloudron
cloudron build
cloudron install --app my-example
cloudron push
```

Refer to `docs/PACKAGING_GUIDE.md` for detailed guidance.

See `docs/APP_STATUS.md` for the automatically generated status table.

## Repository layout

- `apps/` – generated app scaffolds and metadata
- `docs/` – playbooks and architecture notes
- `docs/CI_CD_GITEA.md` – instructions for running CI/CD and publishing images via the Gitea instance
- `docker/packager/` – Docker image for Cloudron packaging workflows
- `scripts/` – helper scripts (scaffolding, tooling entrypoints)
- `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 Harness

Run `./scripts/ci_local.sh` (or `make ci-local`) to execute the same lint and smoke tests that the future Gitea runner will use. Install git hooks via `./scripts/hooks/install_hooks.sh` so pre-commit, post-commit, and pre-push events invoke the harness automatically. Export `SKIP_CI_HOOKS=1` to bypass them when necessary. See `docs/LOCAL_TESTING.md` for full details.

## CI/CD

Once a runner is provisioned, enable `.gitea/workflows/ci.yml` to call the same harness remotely (it currently requires manual `workflow_dispatch`). Mirror `actions/checkout@v4` and label the runner `ubuntu-22.04`. See `docs/CI_CD_GITEA.md` for setup details.