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

docs: establish gardening protocol with STATUS.md and agent guide

Browse Source 
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
This commit is contained in:
mrcharles
2026-07-30 15:49:31 -05:00
parent 32925396dc
commit cbb6c8c75c
2 changed files with 235 additions and 381 deletions
Download Patch File Download Diff File 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**: TSYSDevStack-SupportStack-Cloudron
**Goal**: Package 58 applications for Cloudron PaaS platform
**Timeline**: Started 2025-01-24, ongoing
## Primary Agent: GLM-4.7
**Role**: Development automation and packaging
**Model**: GLM-4.7 via Crush <crush@charm.land>
### Capabilities
- 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>*
Packaging ~57 upstream FLOSS apps for Cloudron — TSYS Group's PaaS of choice.
This repo is the **Cloudron** half of the support stack; the
[Docker-Compose local dev stack](../TSYSDevStack-SupportStack-LocalWorkstation)
is a sibling project. Solo operator, conventional-commit discipline, build
locally then push to `origin/main` on `git.knownelement.com`.