KNEL/TSYSDevStack-SupportStack-Cloudron
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: KNEL/TSYSDevStack-SupportStack-Cloudron:32925396dcd97419eba76d0fd816fc6b83b7ff6b
Branches Tags
KNEL/TSYSDevStack-SupportStack-Cloudron:main
...
compare: KNEL/TSYSDevStack-SupportStack-Cloudron:c56e77c59c581e2c4c1c7972902faa92bc70b8c4
Branches Tags
KNEL/TSYSDevStack-SupportStack-Cloudron:main
2 Commits
32925396dc ... c56e77c59c
Author SHA1 Message Date
mrcharles c56e77c59c docs: reconcile stale package counts across docs 
The docs had drifted to 5/58 packaged while Corteza (and Puter) were
already committed. Reconcile the headline count to 7/~57 everywhere
per the new gardening protocol (GitUrlList.txt is the source of truth
at 57 upstream apps).

- README.md: 5/58 -> 7, add Corteza to completed table, remove false
  "Warp packaged" marker (duplicate, no package), Low-Code 0/3 -> 1/3,
  link STATUS/AGENTS.
- JOURNAL.md: header + repository stats 5/58 -> 7/~57.
- RESUME.md: mark superseded by STATUS.md (was 2025-01-24, referenced
  dead /home/tsys paths) to avoid two competing status docs.

💘 Generated with Crush

Assisted-by: Crush:glm-5.2
 2026-07-30 15:49:35 -05:00
mrcharles cbb6c8c75c docs: establish gardening protocol with STATUS.md and agent guide 
Mirror the agent workflow used across sibling TSYS/KNEL repos
(PFVCluster, KNEL-AIMiddleware): a living agent-maintained STATUS.md
plus a concise AGENTS.md carrying Git Policy and an Automatic Gardening
Protocol that keeps all docs in sync.

- Add STATUS.md: completed packages table (7), per-category progress,
  known issues, next priorities, repo summary. Human read-only; agents
  own it.
- Rewrite AGENTS.md (384 -> 140 lines): repo layout, git policy
  (atomic, conventional, commit+push without prompting), gardening
  protocol, packaging quick-reference. Fixes active model (GLM-4.7 ->
  GLM-5.2), stale counts, and dead /home/tsys paths.

💘 Generated with Crush

Assisted-by: Crush:glm-5.2
 2026-07-30 15:49:31 -05:00
5 changed files with 267 additions and 626 deletions
Expand all files Collapse all files
AGENTS.md
+137 -381
View File
@@ -1,384 +1,140 @@
# AI AGENTS - TSYSDevStack-SupportStack-Cloudron Project # Agent Guidelines — TSYS Cloudron Packaging
**Top-level files:** [`README.md`](README.md) (project overview + app inventory),
[`STATUS.md`](STATUS.md) (living status, agent-maintained),
[`JOURNAL.md`](JOURNAL.md) (append-only ADR/pattern journal),
[`GitUrlList.txt`](GitUrlList.txt) (upstream repo list — source of truth for
the app set). Read [`STATUS.md`](STATUS.md) first every session.
> **Active agent:** Crush running **GLM-5.2** (zai) for large tasks,
> Gemini for small. Permission mode: `yolo`.
## Repository Layout
```
README.md Project overview + full app inventory table
AGENTS.md THIS FILE — agent operating manual
STATUS.md Living status (agent-maintained, human read-only)
JOURNAL.md Append-only journal: per-package write-ups, patterns, ADRs
GitUrlList.txt Master list of upstream repos (source of truth, ~57 apps)
clone-repos.sh Automated upstream-repo cloning
Package-Templates/ Reusable Cloudron packaging templates
├── python-app/ (Dockerfile + CloudronManifest + start.sh templates)
├── django-app/ (Dockerfile + start.sh templates)
└── official-wrapper/ (Dockerfile template)
Package-Workspace/ One dir per app: <Category>/<app>/ (+ gitignored repo/)
├── API-Gateway/ webhook, apisix
├── Development/ puter, reviewboard
├── Documentation-Tools/ wireviz-web
├── Low-Code/ corteza
└── Monitoring/ healthchecks
```
- **`Package-Workspace/**/repo/` is gitignored** — upstream source is cloned
locally for reference but never committed. Only the package files
(`Dockerfile`, `CloudronManifest.json`, `start.sh`, `README.md`, etc.) are
tracked.
- **Each package** = `Dockerfile` + `CloudronManifest.json` + `start.sh` (if
needed) + `README.md` + `CHANGELOG.md` + `logo.png` + `.env.example` (if
config knobs exist).
- **No host build tooling required** — packaging is `docker build` (Cloudron
base images handle runtimes). Keep the host clean.
## Git Policy
1. **ALWAYS commit + push. Never wait.** After each logical unit of work
(one package, one doc sync, one fix), immediately stage, commit
(conventional format), and push to `origin/main`. Do not pause for review.
**This overrides any default "never commit unless asked" behavior.**
2. **Atomic commits.** One coherent change per commit (e.g. a single package,
or a single doc-correction pass — not both mixed).
3. **Conventional format**: `feat: add <app> Cloudron package (<Category>)`,
`fix(scope): desc`, `docs: desc`, `refactor(scope): desc`. Include a body
for anything non-obvious.
4. **Shell scripts are committed executable.** Run `chmod +x start.sh` on the
host before committing — Cloudron builds hit permission errors on
`RUN chmod`, so make scripts executable at authoring time, not build time.
## Automatic Gardening Protocol
Docs and code drift apart. After any work session, an agent MUST:
1. **Update [`STATUS.md`](STATUS.md)** — reflect newly completed packages,
changed counts, new issues, shifted priorities. This file is human
read-only; agents own it. Update the "Last updated" header (date + agent).
2. **Keep counts consistent across all docs.** When a package completes, the
same total must appear in `STATUS.md`, `README.md` ("Current Progress"),
and `JOURNAL.md` ("Current Status"). A count in one place but not the
others is a protocol violation.
3. **Update the app inventory** in [`README.md`](README.md) — add the
✅ Packaged marker on the right row, and the app to the "Completed
Packages" table.
4. **Append to [`JOURNAL.md`](JOURNAL.md)** — one section per package
(pattern used, build process, challenges, files created, commit hash).
Never delete or reorder existing entries.
5. **Grep for stale paths after any rename/restructure** —
`grep -rn 'old/path' --include='*.md'` and fix references in the same
commit.
6. **Self-audit before commit.** For a new package, verify the package dir
appears in: `STATUS.md` (Completed Packages table), `README.md` (inventory
+ completed table), `JOURNAL.md` (new section).
7. **Treat `GitUrlList.txt` as the source of truth** for the app set. If the
README inventory table disagrees, reconcile the README to the list, not
the other way around.
## Key Scripts
| Script | Purpose |
|--------|---------|
| [`clone-repos.sh`](clone-repos.sh) | Clone all upstream repos into `Package-Workspace/<Category>/<app>/repo/` |
## Key Docs
| Doc | Purpose |
|-----|---------|
| [`STATUS.md`](STATUS.md) | Current state, completed packages, known issues, next priorities |
| [`JOURNAL.md`](JOURNAL.md) | Per-package write-ups, the 5 packaging patterns, challenges & solutions |
| [`README.md`](README.md) | Project overview + full app inventory + category breakdown |
| [`GitUrlList.txt`](GitUrlList.txt) | Master upstream repo list (source of truth) |
| [`Package-Templates/`](Package-Templates/) | Reusable templates per packaging pattern |
## Cloudron Packaging — Quick Reference
**Pick a pattern** (see JOURNAL.md for full templates and worked examples):
| Pattern | When | Examples |
|---------|------|----------|
| Official-image wrapper | App ships a usable Docker image | APISIX, Healthchecks, Review Board |
| Multi-stage build | App needs compiling | Webhook (Go), Puter (Node.js) |
| Python build | Python app with deps | WireViz Web |
| Django + PostgreSQL | Django web app | Healthchecks, Review Board |
| Pre-compiled binaries | Upstream ships release binaries | Corteza |
**Standard package steps:**
1. `mkdir -p Package-Workspace/<Category>/<app>/` and clone upstream into `repo/`.
2. Write `Dockerfile` + `CloudronManifest.json` (+ `start.sh` if runtime setup needed).
3. `docker build` to validate locally.
4. Write `README.md` + `CHANGELOG.md` + `logo.png` (+ `.env.example`).
5. Commit as `feat: add <app> Cloudron package (<Category>)`, push.
6. Run the gardening protocol above (update STATUS / README / JOURNAL).
**Recurring gotchas (from JOURNAL.md):**
- `chmod` in `RUN` fails on Cloudron base → make scripts executable on the host.
- Don't `apk`/`apt-get` in base images that lack the package manager; use the
image's built-in tooling or pick the right base.
- Wait for DB/etcd addons in `start.sh` before running migrations.
- Prefer `npm install` over `npm ci` when lockfiles don't match the build env.
- Define every TCP port explicitly in `CloudronManifest.json`.
## Addons — Environment Variables
PostgreSQL: `CLOUDRON_POSTGRESQL_{HOST,PORT,DATABASE,USERNAME,PASSWORD}`.
etcd: `CLOUDRON_ETCD_{HOST,PORT}`. Localstorage mounts at `/app/data`.
## Project Context ## Project Context
**Project**: TSYSDevStack-SupportStack-Cloudron
**Goal**: Package 58 applications for Cloudron PaaS platform
**Timeline**: Started 2025-01-24, ongoing
## Primary Agent: GLM-4.7 Packaging ~57 upstream FLOSS apps for Cloudron — TSYS Group's PaaS of choice.
**Role**: Development automation and packaging This repo is the **Cloudron** half of the support stack; the
**Model**: GLM-4.7 via Crush <crush@charm.land> [Docker-Compose local dev stack](../TSYSDevStack-SupportStack-LocalWorkstation)
is a sibling project. Solo operator, conventional-commit discipline, build
### Capabilities locally then push to `origin/main` on `git.knownelement.com`.
- Dockerfile creation and optimization
- CloudronManifest.json generation
- Start script development
- README documentation writing
- Multi-language support (Go, Python, Node.js, Django, etc.)
- Troubleshooting and error resolution
### Current Tasks
1. Create Cloudron packages for 58 applications
2. Write comprehensive documentation
3. Optimize Docker images for size
4. Ensure all packages follow Cloudron best practices
5. Test and validate packages
### Performance Metrics
- **Packages Completed**: 5/58 (8.6%)
- **Average Package Time**: ~30 minutes
- **Success Rate**: 100% (all packages built successfully)
- **Code Quality**: High (conventional commits, atomic changes)
### Patterns Recognized
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 Build**: For Python applications (WireViz Web)
4. **Django Pattern**: For Django-based apps (Healthchecks, Review Board)
5. **Database Integration**: PostgreSQL, etcd, MySQL patterns
## Knowledge Base
### Cloudron Packaging Patterns
#### Pattern 1: Official Image Wrapper
```dockerfile
FROM official/app:version
COPY start.sh /app/start.sh
CMD ["/app/start.sh"]
```
**Use Cases**: APISIX, Healthchecks, Review Board
**Pros**: Fast builds, upstream maintenance
**Cons**: Limited customization, may include unnecessary dependencies
#### Pattern 2: Multi-Stage Build
```dockerfile
# Build stage
FROM base:builder AS build
RUN install-deps && build-app
# Production stage
FROM base:runtime
COPY --from=build /app/dist /app
CMD ["run-app"]
```
**Use Cases**: Webhook (Go), Puter (Node.js)
**Pros**: Smaller final image, more control
**Cons**: Longer build times, more complex
#### Pattern 3: Python Application
```dockerfile
FROM python:3-slim
RUN apt-get install -y system-deps
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "app.py"]
```
**Use Cases**: WireViz Web
**Pros**: Standard Python environment, easy dependency management
**Cons**: System dependencies may vary
#### Pattern 4: Django Application
```dockerfile
FROM django-image:version
COPY start.sh /app/start.sh
CMD ["/app/start.sh"]
```
**start.sh Pattern**:
```bash
#!/bin/bash
# Wait for database
until psql -h "$DB_HOST" -c '\q'; do
sleep 2
done
# Run migrations
python manage.py migrate --noinput
# Collect static files
python manage.py collectstatic --noinput
# Start application
gunicorn config.wsgi:application
```
**Use Cases**: Healthchecks, Review Board
**Key Points**:
- Wait for database before migrations
- Run collectstatic
- Use gunicorn/uwsgi for production
- Configure PostgreSQL addon
### Common Challenges & Solutions
#### Challenge 1: Permission Denied with chmod
**Error**: `chmod: changing permissions: Operation not permitted`
**Solution**: Make scripts executable on host before COPY
```bash
chmod +x start.sh # On host
# In Dockerfile
COPY start.sh /app/start.sh # No RUN chmod
```
#### Challenge 2: Package Manager Not Found
**Error**: `/bin/bash: apk: command not found`
**Solution**: Use correct package manager for base image
- Alpine: `apk add`
- Debian/Ubuntu: `apt-get install`
- Check base image documentation
#### Challenge 3: npm Build Failures
**Error**: `npm error workspace not found`
**Solution**: Use npm install instead of npm ci for Cloudron
```dockerfile
RUN npm install --production=false --no-optional
# Not: RUN npm ci
```
#### Challenge 4: Large Image Sizes
**Causes**: Including build dependencies, copying entire source
**Solutions**:
- Use multi-stage builds
- Copy only necessary artifacts (dist, node_modules for runtime)
- Use .dockerignore to exclude unnecessary files
- Prefer official images (already optimized)
#### Challenge 5: .dockerignore Interference
**Problem**: Repository's .dockerignore affects Cloudron build
**Solution**: Create custom .dockerignore in package directory
```dockerignore
# Cloudron package .dockerignore
.git
.gitignore
README.md
CHANGELOG.md
```
### Cloudron Best Practices
1. **Always use Cloudron base** when building from scratch
2. **Prefer official images** over custom builds
3. **Define all ports** in CloudronManifest.json
4. **Use appropriate addons** (postgresql, mysql, etcd, localstorage)
5. **Set memory limits** based on application needs
6. **Implement health checks** for all services
7. **Use environment variable defaults**: `${VAR:-default}`
8. **Wait for dependencies** (database, services) before starting
9. **Make scripts executable on host** to avoid permission errors
10. **Document all environment variables** in .env.example
### Addons Reference
#### PostgreSQL
```json
"addons": {
"postgresql": {
"version": "14"
}
}
```
**Environment Variables**:
- `CLOUDRON_POSTGRESQL_HOST`
- `CLOUDRON_POSTGRESQL_PORT`
- `CLOUDRON_POSTGRESQL_DATABASE`
- `CLOUDRON_POSTGRESQL_USERNAME`
- `CLOUDRON_POSTGRESQL_PASSWORD`
#### etcd
```json
"addons": {
"etcd": {
"version": "3.4"
}
}
```
**Environment Variables**:
- `CLOUDRON_ETCD_HOST`
- `CLOUDRON_ETCD_PORT`
#### Localstorage
```json
"addons": {
"localstorage": true
}
```
**Mount Point**: `/app/data`
## Documentation
### JOURNAL.md
**Location**: `/home/tsys/Projects/TDS/TSYSDevStack-SupportStack-Cloudron/JOURNAL.md`
**Purpose**: Detailed packaging journal with learnings, patterns, and challenges
**Contents**:
- Project overview and statistics
- Completed packages with detailed analysis
- Packaging patterns established
- Common challenges & solutions
- Cloudron-specific considerations
- Productivity insights
- Lessons learned summary
**Usage**:
- Read JOURNAL.md for detailed insights on each package
- Reference established patterns when creating new packages
- Learn from challenges and solutions documented
- Use as knowledge base for future packaging work
### GIT URL LIST
**Location**: `/home/tsys/Projects/TDS/TSYSDevStack-SupportStack-Cloudron/GitUrlList.txt`
**Purpose**: List of all 58 applications with GitHub URLs
**Usage**:
- Reference for accessing application repositories
- Check application details and documentation
- Clone repositories as needed
## Conventional Commits
### Commit Message Format
```
<type>(<scope>): <subject>
<body>
<footer>
```
### Types
- `feat`: New feature (new package, new functionality)
- `fix`: Bug fix
- `docs`: Documentation changes
- `refactor`: Code refactoring
- `style`: Code style changes (formatting, etc.)
- `test`: Adding or updating tests
- `chore`: Maintenance tasks
- `perf`: Performance improvements
### Examples
- `feat: add webhook Cloudron package (API-Gateway)`
- `docs: update README.md with usage examples`
- `fix: resolve permission denied error in Dockerfile`
- `refactor: simplify start.sh script`
### Current Practice
- Using `feat:` for all new packages
- Including category in scope: `feat: add <app> Cloudron package (<category>)`
- Detailed body with package information
- Footer with generated message and agent attribution
## Communication
### Project Updates
- **JOURNAL.md**: Updated after each package completion
- **AGENTS.md**: Updated periodically with patterns and insights
- **Git Repository**: All packages committed and pushed
- **Conventional Commits**: Following established format
### Progress Tracking
- **JOURNAL.md**: Comprehensive progress tracking
- **Todo List**: 15 tasks (4 completed, 1 in progress, 10 pending)
- **Git History**: Complete record of all changes
- **Statistics**: 5/58 packages completed (8.6%)
## Expertise Developed
### Cloudron Packaging
- **Expertise**: Advanced knowledge of Cloudron packaging requirements
- **Patterns**: Established 7+ packaging patterns
- **Best Practices**: Comprehensive understanding of Cloudron best practices
- **Troubleshooting**: Experience resolving common packaging issues
### Docker
- **Multi-stage Builds**: Proficient with multi-stage Docker builds
- **Image Optimization**: Skills in optimizing Docker image sizes
- **Dockerfile Writing**: Advanced Dockerfile creation and optimization
- **Base Images**: Knowledge of various base images (Alpine, Debian, Ubuntu)
### Application Technologies
- **Go**: Golang application packaging
- **Python**: Python application packaging with dependencies
- **Node.js**: Node.js application building and optimization
- **Django**: Django application setup with PostgreSQL
- **Flask**: Flask application configuration
- **Various Frameworks**: Experience with multiple application frameworks
### Databases
- **PostgreSQL**: PostgreSQL integration and configuration
- **etcd**: etcd key-value store setup
- **MySQL**: MySQL database configuration
- **Database Migrations**: Running Django migrations on startup
### API Gateways
- **APISIX**: API gateway configuration and etcd integration
- **Webhook**: HTTP endpoint tool configuration
- **REST APIs**: REST API integration patterns
### Documentation
- **README Writing**: Comprehensive README documentation creation
- **Examples**: Practical usage examples
- **Configuration Files**: Detailed configuration file examples
- **Changelog**: Version tracking and change documentation
## Future Recommendations
### Short Term (Next 10-20 Packages)
1. Focus on applications with official Docker images (faster packaging)
2. Prioritize simpler applications (Python, Go, Node.js)
3. Use established patterns to accelerate packaging
4. Leverage JOURNAL.md for reference and learnings
### Medium Term (Next 20-40 Packages)
1. Develop automated package generation script
2. Create template repository for common patterns
3. Implement integration testing for packages
4. Set up CI/CD for package validation
### Long Term (Remaining Packages)
1. Comprehensive security scanning (hadolint, trivy, dockle, dive, syft)
2. Performance benchmarking of all packages
3. Create Cloudron package marketplace submission
4. Develop package maintenance and update workflow
## Continuous Improvement
### Lessons Learned
1. **Documentation is critical** - Saves time in long run
2. **Pattern reuse increases efficiency** - Don't start from scratch each time
3. **Test builds locally** before committing
4. **Commit frequently** with atomic changes
5. **Read official Docker documentation** first
6. **Make scripts executable on host** - Avoids permission errors
7. **Use .dockerignore** - Reduces build context and image size
8. **Wait for dependencies** - Database, services, etc.
9. **Use environment variable defaults** - Improves robustness
10. **Include examples** in README - Users appreciate practical guidance
### Quality Metrics
- **Package Success Rate**: 100% (5/5 packages built successfully)
- **Documentation Quality**: Comprehensive with examples
- **Conventional Commits**: 100% adherence
- **Best Practices**: All packages follow Cloudron best practices
- **Docker Optimization**: All images reasonably sized (<1.5GB average)
## Current Status
### Completed Packages (5/58)
1. Webhook (API-Gateway)
2. APISIX (API-Gateway)
3. Healthchecks (Monitoring)
4. Review Board (Development)
5. WireViz Web (Documentation-Tools)
6. Puter (Development)
### In Progress
- None currently in progress
### Next Priorities
1. Continue with remaining Development applications
2. Move to Monitoring category applications
3. Focus on applications with official Docker images
4. Apply established patterns to increase speed
---
*Last Updated: 2025-01-24*
*Agent: GLM-4.7 via Crush <crush@charm.land>*
JOURNAL.md
+5 -5
View File
@@ -2,9 +2,9 @@
## Project Overview ## Project Overview
**Project**: TSYSDevStack-SupportStack-Cloudron **Project**: TSYSDevStack-SupportStack-Cloudron
**Goal**: Package 58 applications for Cloudron PaaS platform **Goal**: Package ~57 applications for Cloudron PaaS platform
**Start Date**: 2025-01-24 **Start Date**: 2025-01-24
**Current Status**: 5/58 packages completed (8.6%) **Current Status**: 7/~57 packages completed (~12%)
## Completed Packages ## Completed Packages
@@ -626,11 +626,11 @@ Dockerfile
## Repository Statistics ## Repository Statistics
- **Commits**: 6 packages committed to main branch - **Commits**: 7 packages committed to main branch
- **Pushes**: All pushed to remote repository - **Pushes**: All pushed to remote repository
- **Package directories**: Created in Package-Workspace/ - **Package directories**: Created in Package-Workspace/
- **Total packages completed**: 5/58 (8.6%) - **Total packages completed**: 7/~57 (~12%)
- **Remaining packages**: 53/58 (91.4%) - **Remaining packages**: ~50/~57 (~88%)
--- ---
README.md
+14 -11
View File
@@ -8,11 +8,12 @@ The Cloudron component focuses on packaging upstream free/libre/open application
### 📊 Current Progress ### 📊 Current Progress
- **Total Applications**: 58+ - **Total Applications**: ~57 (see [GitUrlList.txt](GitUrlList.txt))
- **Completed Packages**: 5/58 (8.6%) - **Completed Packages**: 7/~57 (~12%)
- **Quick Wins**: 6/6 (100%) ✅
- **Packaging Templates**: Created ✅ - **Packaging Templates**: Created ✅
- **Packages Committed & Pushed**: 6 ✅ - **Packages Committed & Pushed**: 7 ✅
> Living status is tracked in [STATUS.md](STATUS.md) (agent-maintained).
### ✅ Completed Packages ### ✅ Completed Packages
@@ -24,6 +25,7 @@ The Cloudron component focuses on packaging upstream free/libre/open application
| 4 | Review Board | Development | 1.29GB | 8080 | localstorage, postgresql | ✅ Committed | | 4 | Review Board | Development | 1.29GB | 8080 | localstorage, postgresql | ✅ Committed |
| 5 | WireViz Web | Documentation-Tools | 378MB | 3005 | localstorage | ✅ Committed | | 5 | WireViz Web | Documentation-Tools | 378MB | 3005 | localstorage | ✅ Committed |
| 6 | Puter | Development | 361MB | 4100 | localstorage, postgresql | ✅ Committed | | 6 | Puter | Development | 361MB | 4100 | localstorage, postgresql | ✅ Committed |
| 7 | Corteza | Low-Code | 436MB | 80 | localstorage, postgresql | ✅ Committed |
### 📦 Packages in Development ### 📦 Packages in Development
@@ -31,7 +33,7 @@ None currently in development.
### 🔄 Next Steps ### 🔄 Next Steps
1. Continue packaging remaining applications (53 remaining) 1. Continue packaging remaining applications (~50 remaining)
2. Prioritize applications with official Docker images (faster packaging) 2. Prioritize applications with official Docker images (faster packaging)
3. Apply established patterns from Package-Templates/ 3. Apply established patterns from Package-Templates/
4. Reference JOURNAL.md for learnings and best practices 4. Reference JOURNAL.md for learnings and best practices
@@ -40,9 +42,10 @@ None currently in development.
### 📚 Documentation & Resources ### 📚 Documentation & Resources
- **JOURNAL.md**: Detailed packaging journal with patterns, challenges, and insights - **JOURNAL.md**: Detailed packaging journal with patterns, challenges, and insights
- **AGENTS.md**: AI agent documentation and knowledge base - **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 - **Package-Templates/**: Cloudron packaging templates for common patterns
- **GitUrlList.txt**: Complete list of all 58+ applications with GitHub URLs - **GitUrlList.txt**: Source-of-truth list of upstream repos
### 🏗 Cloudron Patterns Established ### 🏗 Cloudron Patterns Established
@@ -56,11 +59,11 @@ None currently in development.
### ⚡ Productivity Metrics ### ⚡ Productivity Metrics
- **Packages Completed**: 5/58 (8.6%) - **Packages Completed**: 7/~57 (~12%)
- **Average Package Time**: ~30 minutes - **Average Package Time**: ~30 minutes
- **Success Rate**: 100% (all packages built successfully) - **Success Rate**: 100% (all packages built successfully)
- **Commits Pushed**: 100% (all packages pushed to remote) - **Commits Pushed**: 100% (all packages pushed to remote)
- **Total Commits**: 7 (1 foundation + 5 packages + 1 templates) - **Total Commits**: 21+ (foundation + 7 packages + templates + docs)
--- ---
@@ -83,7 +86,7 @@ Applications are organized by function rather than programming language:
| **Financial-Trading** | Trading and financial algorithm platforms | 1 | 0/1 (0%) | | **Financial-Trading** | Trading and financial algorithm platforms | 1 | 0/1 (0%) |
| **Infrastructure** | Infrastructure and networking tools | 6 | 0/6 (0%) | | **Infrastructure** | Infrastructure and networking tools | 6 | 0/6 (0%) |
| **Legal** | Legal and compliance applications | 1 | 0/1 (0%) | | **Legal** | Legal and compliance applications | 1 | 0/1 (0%) |
| **Low-Code** | Low-code and no-code platforms | 3 | 0/3 (0%) | | **Low-Code** | Low-code and no-code platforms | 3 | 1/3 (33%) |
| **Monitoring** | Monitoring and observability tools | 6 | 1/6 (17%) | | **Monitoring** | Monitoring and observability tools | 6 | 1/6 (17%) |
| **Project-Management** | Project management solutions | 1 | 0/1 (0%) | | **Project-Management** | Project management solutions | 1 | 0/1 (0%) |
| **Scientific-Computing** | Scientific and research computing | 2 | 0/2 (0%) | | **Scientific-Computing** | Scientific and research computing | 2 | 0/2 (0%) |
@@ -146,7 +149,7 @@ Applications are organized by function rather than programming language:
| [Core](https://github.com/Resgrid/Core) | [GitHub](https://github.com/Resgrid/Core) | Emergency management and incident response system | Project-Management | | [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 | | [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 | | [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 |
| [Warp](https://github.com/sebo-b/warp) | [GitHub](https://github.com/sebo-b/warp) | Terminal and shell enhancement tool | Development | ✅ Packaged | | [Warp](https://github.com/sebo-b/warp) | [GitHub](https://github.com/sebo-b/warp) | Terminal and shell enhancement tool | Development | |
| [Windmill](https://github.com/windmill-labs/windmill) | [GitHub](https://github.com/windmill-labs/windmill) | Open-source workflow automation platform | Automation | | [Windmill](https://github.com/windmill-labs/windmill) | [GitHub](https://github.com/windmill-labs/windmill) | Open-source workflow automation platform | Automation |
| [Corteza](https://github.com/cortezaproject/corteza) | [GitHub](https://github.com/cortezaproject/corteza) | Open-source low-code platform | Low-Code | | [Corteza](https://github.com/cortezaproject/corteza) | [GitHub](https://github.com/cortezaproject/corteza) | Open-source low-code platform | Low-Code |
| [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 | | [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 |
RESUME.md
+13 -229
View File
@@ -1,230 +1,14 @@
# TSYS Cloudron Project - Session Resume Guide # Session Resume Guide — SUPERSEDED
**Date**: 2025-01-24 > **This file is superseded by [`STATUS.md`](STATUS.md).**
**Session Type**: Orientation & Analysis >
**Status**: Ready for Packaging Phase > STATUS.md is now the living, agent-maintained source of truth for project
> state (completed packages, known issues, next priorities). Read STATUS.md at
--- > the start of every session instead of this file.
>
## 🎯 Current Project State > This RESUME.md is retained only for historical reference. It was last updated
> 2025-01-24 and referenced an old host path (`/home/tsys/Projects/TDS/...`)
### What Was Done This Session > that no longer exists — the project now lives at
- ✅ Oriented to project structure > `~/projects/TSYSDevStack-SupportStack-Cloudron`.
- ✅ Analyzed repository cloning status (56/59 successfully cloned) >
- ✅ Reviewed all documentation (README.md, AGENTS.md, GitUrlList.txt) > Do not update this file. Update [`STATUS.md`](STATUS.md) instead.
- ✅ Identified missing repositories
- ✅ Assessed workspace organization (19 functional categories)
- ✅ Documented uncommitted changes
### What Needs To Be Committed
```bash
git status
# Modified: README.md
# Untracked: AGENTS.md, GitUrlList.txt, clone-repos.sh, .gitignore, Package-Workspace/
```
**Suggested Commit Message:**
```
feat: add Cloudron packaging foundation and upstream repositories
- Add comprehensive README.md with 59-app inventory table
- Create AGENTS.md for AI agent context and decisions
- Add GitUrlList.txt with all upstream repository URLs
- Implement clone-repos.sh automation script
- Configure .gitignore to exclude cloned repos
- Clone and organize 56 upstream repositories by function
- Establish 19 functional categories for better organization
```
---
## 📊 Repository Status
### Successfully Cloned (58 repos)
All repos are organized in `Package-Workspace/<Category>/<App>/repo/`
### Excluded Repositories (4 repos)
1. **oat-sa** - Invalid URL (organization-level only, not a repository)
- Status: Excluded from project
2. **satnogs** - GitLab repository requiring authentication
- Category: Infrastructure
- URL: https://gitlab.com/librespacefoundation/satnogs
- Status: Excluded from project
3. **warp** - Duplicate entry removed
- Category: Development
- Status: Single entry retained
4. **windmill** - Duplicate entry removed
- Category: Automation
- Status: Single entry retained
### Previously Failed Clones - Now Fixed
1. **WireViz** - Successfully cloned on retry
- Category: Documentation-Tools
- Status: ✅ Complete
2. **elabftw** - Successfully cloned on retry
- Category: Business-Apps
- Status: ✅ Complete
### Special Case: docassemble
- Cloned directly to `Package-Workspace/Legal/docassemble/` (not `repo/` subdirectory)
- This is the only repo not following the standard structure
- Decision: Leave as-is or restructure if needed
---
## 🚀 Immediate Next Steps
### Step 1: Commit Current Work (10 minutes)
```bash
cd /home/tsys/Projects/TDS/TSYSDevStack-SupportStack-Cloudron
git add README.md AGENTS.md GitUrlList.txt clone-repos.sh .gitignore RESUME.md
git commit -m "feat: add Cloudron packaging foundation and upstream repositories"
```
**Note**: `Package-Workspace/` is excluded by `.gitignore`, so it won't be committed.
### Step 2: Begin Cloudron Packaging (start with easy apps)
Pick a high-priority application and start packaging:
**Example workflow:**
```bash
cd Package-Workspace/Monitoring/healthchecks/repo
# Study existing Cloudron packages for patterns
# Create Dockerfile
# Create CloudronManifest.json
# Test: cloudron build
# Test: cloudron install
```
---
## 📋 Project Statistics
- **Total Applications**: 58
- **Successfully Cloned**: 58
- **Failed Clones**: 0
- **Functional Categories**: 20
- **Workspace Size**: 5.4GB
- **Programming Languages**: 9+ (Go, Node.js, Python, PHP, Java, Rust, Ruby, TypeScript)
---
## 🗂️ Functional Categories Summary
| Category | Apps | Status |
|----------|------|--------|
| API-Gateway | 2 | 2/2 cloned |
| Automation | 4 | 4/4 cloned |
| Business-Apps | 8 | 8/8 cloned |
| Collaboration | 2 | 2/2 cloned |
| Communication | 2 | 2/2 cloned |
| Data-Management | 2 | 2/2 cloned |
| Development | 4 | 4/4 cloned |
| DevOps-Tools | 2 | 2/2 cloned |
| Documentation-Tools | 3 | 3/3 cloned |
| Financial-Payments | 1 | 1/1 cloned |
| Financial-Trading | 1 | 1/1 cloned |
| Infrastructure | 5 | 5/5 cloned |
| Legal | 1 | 1/1 cloned |
| Low-Code | 3 | 3/3 cloned |
| Monitoring | 6 | 6/6 cloned |
| Project-Management | 1 | 1/1 cloned |
| Scientific-Computing | 2 | 2/2 cloned |
| Security | 5 | 5/5 cloned |
| System-Administration | 3 | 3/3 cloned |
---
## 📚 Key Resources
### Documentation
- `README.md` - Complete project overview and app inventory
- `AGENTS.md` - AI agent context, decisions, and working patterns
- `RESUME.md` - This file
### Scripts & Tools
- `clone-repos.sh` - Automated repository cloning
- `GitUrlList.txt` - Master list of upstream repositories
### Cloudron Packaging
- [Cloudron Packaging Tutorial](https://docs.cloudron.io/packaging/tutorial/)
- [Cloudron Manifest Documentation](https://docs.cloudron.io/packaging/manifest/)
- [Cloudron CLI Documentation](https://docs.cloudron.io/packaging/cli/)
- [Existing Cloudron Packages](https://git.cloudron.io/cloudron)
---
## 🔧 Recommended Starting Points
### For Cloudron Packaging Beginners
Start with simple applications that likely have existing Docker setups:
1. **Review Board** - Development (likely has simple setup)
2. **Webhook** - API-Gateway (lightweight Go app)
3. **Healthchecks** - Monitoring (Python, well-documented)
### For Quick Wins (apps with existing Dockerfiles)
1. **Puter** - Development (has Dockerfile)
2. **Windmill** - Automation (has Dockerfile)
3. **DataHub** - Data-Management (has Docker setup)
### For High Business Value
1. **InvenTree** - Business-Apps (inventory management)
2. **NetBox** - Infrastructure (data center management)
3. **Grist Core** - Collaboration (data spreadsheet)
---
## ⚠️ Known Issues
1. **docassemble Structure**
- Not following standard `repo/` subdirectory pattern
- Cloned directly to `Package-Workspace/Legal/docassemble/`
- Action: Document as exception (non-standard structure)
2. **Excluded Repositories**
- oat-sa: Organization URL (not a repository)
- satnogs: Requires authentication (GitLab)
- Both intentionally excluded from project scope
---
## 📞 How to Resume
1. **Navigate to project:**
```bash
cd /home/tsys/Projects/TDS/TSYSDevStack-SupportStack-Cloudron
```
2. **Review this file:**
```bash
cat RESUME.md
```
3. **Check git status:**
```bash
git status
```
4. **Pick up where you left off:**
- If uncommitted: Commit current work
- If ready to package: Choose an app and start
- If missing repos: Retry cloning
---
## 🎯 Project Goals Checklist
- [x] Fix and retry failed repository clones
- [x] Commit current foundation work
- [x] Clean up duplicate entries in GitUrlList.txt
- [ ] Start Cloudron packaging (Dockerfile + CloudronManifest.json)
- [ ] Test packages with Cloudron CLI
- [ ] Move completed packages to `Package-Artifacts/`
- [ ] Establish testing/validation pipeline
- [ ] Complete packaging for all 58 apps by deadline
---
**Last Updated**: 2025-01-24
**Status**: Foundation complete, all repos cloned, ready for packaging phase
**Next Session**: Start Cloudron packaging with Phase 2 (Quick Wins & Templates)
STATUS.md
+98
View File
@@ -0,0 +1,98 @@
# Project Status
> **Human read-only. Agents maintain this file automatically after each work
> session.** Do not edit by hand — the next agent run will overwrite it.
>
> **Last updated:** 2026-07-30 by Crush (GLM-5.2) — gardening protocol established;
> inventory counts reconciled to 7 packaged / 57 upstream apps.
## Current State: STABLE (packaging phase, ongoing)
Cloudron packaging pipeline is operational. 7 of ~57 upstream applications are
packaged, committed, and pushed. Packaging templates exist for the four core
patterns. The gardening protocol (this file + AGENTS.md) was just established
to keep docs in sync going forward.
## Completed Packages (7)
| # | Application | Category | Pattern | Port(s) | Addons |
|---|-------------|----------|---------|---------|--------|
| 1 | Webhook | API-Gateway | Multi-stage (Go) | 9000 | localstorage |
| 2 | APISIX | API-Gateway | Official-image wrapper | 9080, 9180, 9443 | localstorage, etcd |
| 3 | Healthchecks | Monitoring | Django + PostgreSQL | 8000 | localstorage, postgresql |
| 4 | Review Board | Development | Django + PostgreSQL | 8080 | localstorage, postgresql |
| 5 | WireViz Web | Documentation-Tools | Python build | 3005 | localstorage |
| 6 | Puter | Development | Multi-stage (Node.js) | 4100 | localstorage, postgresql |
| 7 | Corteza | Low-Code | Pre-compiled binaries | 80 | localstorage, postgresql |
Each package lives in `Package-Workspace/<Category>/<app>/` and contains a
`Dockerfile`, `CloudronManifest.json`, `README.md`, `CHANGELOG.md`, `logo.png`,
and (where relevant) `start.sh` + `.env.example`.
## Packaging Patterns Established
1. **Official-image wrapper** — APISIX, Healthchecks, Review Board
2. **Multi-stage build** — Webhook (Go), Puter (Node.js)
3. **Python build** — WireViz Web
4. **Django + PostgreSQL** — Healthchecks, Review Board
5. **Pre-compiled binaries** — Corteza (download + extract from upstream releases)
Templates live in `Package-Templates/` (python-app, django-app, official-wrapper).
Full write-ups of each pattern + challenges are in [`JOURNAL.md`](JOURNAL.md).
## Progress by Category
| Category | Apps | Packaged | Notes |
|----------|------|----------|-------|
| **API-Gateway** | 2 | 2/2 (100%) ✅ | Category complete |
| Development | 4 | 2/4 | reviewboard, puter done |
| Documentation-Tools | 3 | 1/3 | wireviz-web done |
| Low-Code | 3 | 1/3 | corteza done |
| Monitoring | 6 | 1/6 | healthchecks done |
| Automation | 4 | 0/4 | |
| Business-Apps | 8 | 0/8 | |
| Collaboration | 2 | 0/2 | |
| Communication | 1 | 0/1 | |
| Data-Management | 2 | 0/2 | |
| DevOps-Tools | 1 | 0/1 | |
| Financial-Payments | 1 | 0/1 | |
| Financial-Trading | 1 | 0/1 | |
| Infrastructure | 6 | 0/6 | |
| Legal | 1 | 0/1 | |
| Project-Management | 1 | 0/1 | |
| Scientific-Computing | 2 | 0/2 | |
| Security | 5 | 0/5 | |
| System-Administration | 2 | 0/2 | |
## Known Issues
| Issue | Impact | Status |
|-------|--------|--------|
| **Inventory count drift** | GitUrlList.txt has 57 apps; README inventory table lists 55; some entries differ (e.g. `todogroup/policies`, `CraigChat/craig` in GitUrlList but not README table) | Reconcile on next packaging pass — treat GitUrlList.txt as source of truth |
| **Erroneous "Warp" packaged marker** | README inventory row marked Warp ✅ Packaged, but Warp is a duplicate (per RESUME) and no package dir exists | Fixed in this session (README marker removed) |
| **No CI / build validation** | Packages are built but not regression-tested in a pipeline | Future: `cloudron build` + manifest lint in CI |
| **Packages not exercised on a live Cloudron** | Untested end-to-end on the production Cloudron VPS | Future: install-test a sample package |
| **Architecture is amd64-only** | Pre-compiled-binary + multi-stage packages target linux/amd64 | Acceptable for current target host |
## Pending (next session priorities)
1. **Reconcile the app inventory** — make GitUrlList.txt ↔ README inventory
table ↔ Package-Workspace agree on the exact app set + categories.
2. **Pick the next quick wins** — prefer apps with official Docker images
(e.g. Windmill, DataHub, Sentry/SigNoz, NetBox, InvenTree).
3. **Validate one package end-to-end** on the Cloudron VPS to prove the
packaging patterns in production, not just at build time.
4. **Stand up CI** — `cloudron build` + CloudronManifest.json schema lint on
every package change.
5. Continue category-by-category until all ~57 apps are packaged.
## Repository Summary
| Component | Details |
|-----------|---------|
| Goal | Package ~57 upstream FLOSS apps for Cloudron (TSYS PaaS of choice) |
| Upstream source list | [`GitUrlList.txt`](GitUrlList.txt) (57 repos) |
| Workspace | `Package-Workspace/<Category>/<app>/` (cloned upstream `repo/` dirs are gitignored) |
| Templates | `Package-Templates/` (python-app, django-app, official-wrapper) |
| Git remote | `ssh://git@git.knownelement.com:29418/KNEL/TSYSDevStack-SupportStack-Cloudron.git` (`origin/main`) |
| Sibling project | [`TSYSDevStack-SupportStack-LocalWorkstation`](../TSYSDevStack-SupportStack-LocalWorkstation) (local Docker-Compose dev stack) |