KNEL-TSYSDevStack-SupportStack-Cloudron/README.md

# TSYS Cloudron Packaging Project

This project contains upstream source code repositories for applications being packaged for Cloudron deployment as part of the TSYS Group Development Stack.

## 🚀 Project Overview

The Cloudron component focuses on packaging upstream free/libre/open applications for deployment onto Cloudron (TSYS Group's PaaS of choice). This is a massive undertaking involving **58+ applications** across **20 functional categories**.

### 📊 Current Progress

- **Total Applications**: 36 (see [GitUrlList.txt](GitUrlList.txt); pruned 2026-09-06 by rulings: no-Node, no-open-core, no-SSO-tax, k8s redirects, out-of-scope)
- **Completed Packages**: 18/36 (50% of the post-ruling set)
- **Packaging Templates**: Created ✅
- **Packages Committed & Pushed**: 18 ✅ (rathole removed by ruling)
- **Build Tickets**: rulings synced 2026-09-06 (#633-#678 batch, umbrella
  [#632](https://projects.knownelement.com/issues/632), Redmine project 55);
  grist-core excluded (packaged upstream)

> Living status is tracked in [STATUS.md](STATUS.md) (agent-maintained).

### ✅ Completed Packages

| # | Application | Category | Size | Ports | Addons | Status |
|---|------------|----------|-------|--------|---------|--------|
| 1 | Webhook | API-Gateway | 775MB | 9000 | localstorage | ✅ Committed |
| 2 | APISIX | API-Gateway | ~700MB | 9080 | localstorage (embedded etcd) | ✅ **DEPLOYED** apigw.knownelement.com |
| 3 | Healthchecks | Monitoring | 105MB | 8000 | localstorage, postgresql | ✅ Committed |
| 4 | Review Board | Development | 1.29GB | 8080 | localstorage, postgresql | ✅ Committed |
| 5 | WireViz Web | Documentation-Tools | 378MB | 3005 | localstorage | ✅ Committed |
| 6 | Puter | Development | 361MB | 4100 | localstorage, postgresql | ✅ Committed |
| 7 | Corteza | Low-Code | 436MB | 80 | localstorage, postgresql | ✅ Committed |
| 8 | draw.io | Documentation-Tools | — | 8080 | none (auth proxy) | ✅ Committed |
| 9 | Windmill | Automation | ~2GB | 8000 | localstorage, postgresql | ✅ Committed |
| 10 | Easy-Gate | Infrastructure | 3.18GB | 8080 | localstorage (auth proxy) | ✅ Committed |
| 11 | Database Gateway | Infrastructure | 93.7MB | 8080 | localstorage, postgresql | ✅ Committed |
| 12 | FX | DevOps-Tools | 3.55GB | 8000 | localstorage (auth proxy) | ✅ Committed |
| 13 | ChirpStack | Infrastructure | 83.4MB | 8080 | localstorage, postgresql, redis | ✅ Committed |
| 14 | eLabFTW | Business-Apps | ~209MB (compressed) | 443 | localstorage, mysql, ldap | ✅ Committed |
| 15 | NetBox | Infrastructure | ~1GB | 8080 | localstorage, postgresql, redis | ✅ Committed |
| 16 | ConsulDemocracy | Collaboration | ~1.6GB | 3000 | localstorage, postgresql | ✅ Committed |
| 17 | GoAlert | Monitoring | ~40MB | 8081 | localstorage, postgresql | ✅ Committed |
| 18 | InvenTree | Business-Apps | ~1.4GB | 8000 | localstorage, postgresql, redis | ✅ Committed |

### 📦 Packages in Development

None currently in development.

### 🔄 Next Steps

1. Continue packaging remaining applications (~50 remaining)
2. Prioritize applications with official Docker images (faster packaging)
3. Apply established patterns from Package-Templates/
4. Reference JOURNAL.md for learnings and best practices
5. Focus on simpler applications before complex ones

### 📚 Documentation & Resources

- **JOURNAL.md**: Detailed packaging journal with patterns, challenges, and insights
- **STATUS.md**: Living status (completed packages, known issues, next priorities) — agent-maintained
- **AGENTS.md**: Agent operating manual + gardening protocol
- **Package-Templates/**: Cloudron packaging templates for common patterns
- **GitUrlList.txt**: Source-of-truth list of upstream repos

### 🏗 Cloudron Patterns Established

1. **Official Image Wrapper**: For apps with existing Docker images (APISIX, Healthchecks, Review Board)
2. **Multi-Stage Build**: For compiled applications (Webhook - Go, Puter - Node.js)
3. **Python Application**: For Python apps (WireViz Web)
4. **Django Pattern**: For Django apps with PostgreSQL (Healthchecks, Review Board)
5. **Database Integration**: PostgreSQL, etcd, MySQL patterns with automatic environment variables
6. **Multiple Ports**: Explicit port definitions in CloudronManifest.json
7. **Health Check**: Docker HEALTHCHECK and CloudronManifest.json healthCheckPath

### ⚡ Productivity Metrics

- **Packages Completed**: 13/~57 (~23%)
- **Average Package Time**: ~30 minutes
- **Success Rate**: 100% (all packages built successfully)
- **Commits Pushed**: 100% (all packages pushed to remote)
- **Total Commits**: 21+ (foundation + 7 packages + templates + docs)

---

## 📁 Functional Organization

Applications are organized by function rather than programming language:

| Functional Category | App Count | Packages Completed |
|---|---|---|
| **API-Gateway** | 2 | 2/2 (100%) ✅ |
| **Automation** | 1 | 1/1 (100%) ✅ |
| **Business-Apps** | 4 | 2/4 (50%) |
| **Collaboration** | 2 | 1/2 (50%) |
| **Data-Management** | 2 | 0/2 (0%) |
| **Development** | 2 | 2/2 (100%) ✅ |
| **DevOps-Tools** | 1 | 1/1 (100%) ✅ |
| **Documentation-Tools** | 2 | 2/2 (100%) ✅ |
| **Financial-Trading** | 1 | 0/1 (0%) |
| **Infrastructure** | 5 | 4/5 (80%) |
| **Legal** | 1 | 0/1 (0%) |
| **Low-Code** | 2 | 1/2 (50%) |
| **Monitoring** | 4 | 2/4 (50%) |
| **Project-Management** | 1 | 0/1 (0%) |
| **Scientific-Computing** | 2 | 0/2 (0%) |
| **Security** | 2 | 0/2 (0%) |
| **System-Administration** | 1 | 0/1 (0%) |

**Categories with 100% completion**: API-Gateway ✅ · Automation ✅ · Development ✅ · DevOps-Tools ✅ · Documentation-Tools ✅


## 📋 Application Inventory

| Application Name | Repository | Description | Functional Category | Package Status |
|---|---|---|---|---|
| [GoAlert](https://github.com/target/goalert) | [GitHub](https://github.com/target/goalert) | On-call scheduling, escalation, and alerting platform | Monitoring | ✅ Packaged |
| [DataHub](https://github.com/datahub-project/datahub) | [GitHub](https://github.com/datahub-project/datahub) | Modern data stack for end-to-end data management | Data-Management |
| [Docassemble](https://github.com/jhpyle/docassemble) | [GitHub](https://github.com/jhpyle/docassemble) | Open-source expert system for guided interviews | Legal |
| [Database-Gateway](https://github.com/kazhuravlev/database-gateway) | [GitHub](https://github.com/kazhuravlev/database-gateway) | Database gateway and connection management | Infrastructure | ✅ Packaged |
| [Webhook](https://github.com/adnanh/webhook) | [GitHub](https://github.com/adnanh/webhook) | Lightweight webhook receiver | API-Gateway | ✅ Packaged |
| [FX](https://github.com/metrue/fx) | [GitHub](https://github.com/metrue/fx) | Function as a Service platform | DevOps-Tools | ✅ Packaged |
| [PayrollEngine](https://github.com/Payroll-Engine/PayrollEngine) | [GitHub](https://github.com/Payroll-Engine/PayrollEngine) | Payroll processing engine | Business-Apps |
| [Nautilus Trader](https://github.com/nautechsystems/nautilus_trader) | [GitHub](https://github.com/nautechsystems/nautilus_trader) | Algorithmic trading platform | Financial-Trading |
| [APISIX](https://github.com/apache/apisix) | [GitHub](https://github.com/apache/apisix) | Cloud-native API gateway | API-Gateway | ✅ **DEPLOYED** ([apigw.knownelement.com](https://apigw.knownelement.com)) |
| [Grist Core](https://github.com/gristlabs/grist-core) | [GitHub](https://github.com/gristlabs/grist-core) | Modern data spreadsheet and database | Collaboration | ⏭ Excluded — packaged upstream (Cloudron App Store) |
| [Healthchecks](https://github.com/healthchecks/healthchecks) | [GitHub](https://github.com/healthchecks/healthchecks) | Cron job monitoring service | Monitoring | ✅ Packaged |
| [EmonCMS](https://github.com/emoncms/emoncms) | [GitHub](https://github.com/emoncms/emoncms) | OpenEnergyMonitor energy monitoring platform | Monitoring | ❓ local-only auth — founder ruling (#907) |
| [Fleet](https://github.com/fleetdm/fleet) | [GitHub](https://github.com/fleetdm/fleet) | Device management and monitoring | Monitoring |
| [NetBox](https://github.com/netbox-community/netbox) | [GitHub](https://github.com/netbox-community/netbox) | IP address management (IPAM) and data center infrastructure management | Infrastructure | ✅ Packaged
| [SeaTunnel](https://github.com/apache/seatunnel) | [GitHub](https://github.com/apache/seatunnel) | Data integration and streaming platform | Data-Management |
| [Easy-Gate](https://github.com/wiredlush/easy-gate) | [GitHub](https://github.com/wiredlush/easy-gate) | Gateway and proxy solution | Infrastructure | ✅ Packaged |
| [ConsulDemocracy](https://github.com/consuldemocracy/consuldemocracy) | [GitHub](https://github.com/consuldemocracy/consuldemocracy) | Open-source citizen participation platform | Collaboration | ✅ Packaged
| [BOINC](https://github.com/BOINC/boinc) | [GitHub](https://github.com/BOINC/boinc) | Open-source software for volunteer computing | Scientific-Computing |
| [Slurm](https://github.com/SchedMD/slurm) | [GitHub](https://github.com/SchedMD/slurm) | Workload manager and job scheduling system | System-Administration |
| [SniperPhish](https://github.com/GemGeorge/SniperPhish) | [GitHub](https://github.com/GemGeorge/SniperPhish) | Phishing campaign management platform | Security |
| [InvenTree](https://github.com/inventree/InvenTree) | [GitHub](https://github.com/inventree/InvenTree) | Open-source inventory management system | Business-Apps | ✅ Packaged |
| [WireViz Web](https://github.com/wireviz/wireviz-web) | [GitHub](https://github.com/wireviz/wireviz-web) | Cable and wiring harness visualization tool | Documentation-Tools | ✅ Packaged |
| [KillBill](https://github.com/killbill/killbill) | [GitHub](https://github.com/killbill/killbill) | Open-source subscription billing and payment platform | Business-Apps |
| [Docker DrawIO](https://github.com/jgraph/docker-drawio) | [GitHub](https://github.com/jgraph/docker-drawio) | Dockerized version of Draw.io diagramming tool | Documentation-Tools | ✅ Packaged |
| [Sentry](https://github.com/getsentry/sentry) | [GitHub](https://github.com/getsentry/sentry) | Error tracking and performance monitoring | Monitoring |
| [ChirpStack](https://github.com/chirpstack/chirpstack) | [GitHub](https://github.com/chirpstack/chirpstack) | Open-source LoRaWAN network server | Infrastructure | ✅ Packaged |
| [eLabFTW](https://github.com/elabftw/elabftw) | [GitHub](https://github.com/elabftw/elabftw) | Electronic lab notebook for research teams | Business-Apps | ✅ Packaged
| [Jamovi](https://github.com/jamovi/jamovi) | [GitHub](https://github.com/jamovi/jamovi) | Statistical spreadsheet software | Scientific-Computing |
| [Review Board](https://github.com/reviewboard/reviewboard) | [GitHub](https://github.com/reviewboard/reviewboard) | Code review and collaboration tool | Development | ✅ Packaged |
| [Core](https://github.com/Resgrid/Core) | [GitHub](https://github.com/Resgrid/Core) | Emergency management and incident response system | Project-Management |
| [SDRangel](https://github.com/f4exb/sdrangel) | [GitHub](https://github.com/f4exb/sdrangel) | Software defined radio application | Infrastructure |
| [No-Code Architects Toolkit](https://github.com/stephengpope/no-code-architects-toolkit) | [GitHub](https://github.com/stephengpope/no-code-architects-toolkit) | No-code development toolkit | Low-Code |
| [Windmill](https://github.com/windmill-labs/windmill) | [GitHub](https://github.com/windmill-labs/windmill) | Open-source workflow automation platform | Automation | ✅ Packaged |
| [Corteza](https://github.com/cortezaproject/corteza) | [GitHub](https://github.com/cortezaproject/corteza) | Open-source low-code platform | Low-Code | ✅ Packaged
| [Security Awareness Training](https://github.com/security-companion/security-awareness-training) | [GitHub](https://github.com/security-companion/security-awareness-training) | Security awareness training platform | Security |
| [Puter](https://github.com/HeyPuter/puter) | [GitHub](https://github.com/HeyPuter/puter) | The Internet OS - Personal Cloud Computer | Development | ✅ Packaged |

**Package Status Legend**:
- ✅ Packaged: Complete Cloudron package created and committed
- ⏳ In Progress: Currently being packaged
- 📦 Repository: Source repository cloned, packaging not started
- ❌ Complex: Requires significant packaging effort
- ⏭ Excluded: Not packaged here (already available for Cloudron upstream)
- ❓ Disposition: verify-and-close review (dupes, non-apps, out-of-scope)