# AI AGENTS - TSYSDevStack-SupportStack-Cloudron Project ## 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 ### 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 ``` ():