KNELProductionContainers/README.md

KNEL Production Containers - Cloudron Packaging Repository

This repository contains the infrastructure and tooling for packaging applications for Cloudron, KNEL's self-hosted application platform. We're systematically packaging ~100 applications for internal deployment and potential contribution to the Cloudron app store.

🏗️ Repository Structure

KNELProductionContainers/
├── [README.md](README.md)                          # This file
├── [PLAN.md](PLAN.md)                           # Overall packaging strategy and roadmap  
├── [TASKS.md](TASKS.md)                          # Application checklist and status
├── [WORKLOG.md](WORKLOG.md)                        # Development progress log
├── [.gitignore](.gitignore)                        # Git exclusions for workspace
│
├── [CloudronPackages/](CloudronPackages/)                 # ✅ Final tested packages (tracked in git)
│   ├── [PackageTemplate/](CloudronPackages/PackageTemplate/)             # Template and LLM prompts
│   ├── [EasyGate/](CloudronPackages/EasyGate/)                    # Completed packages
│   └── [AppName]/                   # Individual app packages
│
├── [CloudronPackagingWorkspace/](CloudronPackagingWorkspace/)      # 🚧 Development workspace  
│   ├── Docker/ (gitignored)         # ~100 cloned upstream repositories
│   ├── NonDocker/ (gitignored)      # Non-Docker applications
│   ├── [UpstreamVendor-Clone.sh](CloudronPackagingWorkspace/UpstreamVendor-Clone.sh)     # Script to clone upstream sources
│   └── [UpstreamVendor-Update.sh](CloudronPackagingWorkspace/UpstreamVendor-Update.sh)    # Script to update upstream sources
│
├── [KNEL-Cloudron/](KNEL-Cloudron/)                   # 🏢 KNEL-specific deployment configs
└── [KNEL-NonCloudron/](KNEL-NonCloudron/)               # Non-Cloudron container configs

🚀 Quick Start

Prerequisites

• Docker (for containerized packaging)
• Cloudron CLI: npm install -g cloudron
• Git access to upstream repositories

Setup Development Environment

# Clone this repository
git clone [repository-url]
cd KNELProductionContainers

# Set up packaging container (persistent across sessions)
docker run -d --name tsys-cloudron-packaging \
  -v $(pwd):/workspace \
  -w /workspace \
  python:3.11-slim tail -f /dev/null

# Install tools in container
docker exec tsys-cloudron-packaging sh -c "
  apt-get update && apt-get install -y git curl build-essential nodejs npm
"

# Clone upstream application sources
chmod +x CloudronPackagingWorkspace/*.sh
./CloudronPackagingWorkspace/UpstreamVendor-Clone.sh

📋 Packaging Workflow

1. Choose Application

• Check TASKS.md for priority applications
• Verify upstream source is available in CloudronPackagingWorkspace/Docker/

2. Create Feature Branch

# Start from integration branch (not main!)
git checkout integration
git pull origin integration
git checkout -b feature/package-[appname]

3. Package Development

# Work in the persistent container
docker exec -it tsys-cloudron-packaging bash

# Create package structure
cd /workspace
mkdir -p [appname]_package_new
cd [appname]_package_new

# Create required files:
# - CloudronManifest.json
# - Dockerfile  
# - start.sh
# - [config files]

4. Build and Test

# Build container
docker build -t registry/[appname]:version .

# Test locally if possible
docker run --rm -p 8080:8080 registry/[appname]:version

# Deploy to test Cloudron instance
cloudron install --image registry/[appname]:version

5. Finalize Package

# Move to final location
mv /workspace/[appname]_package_new ./CloudronPackages/[AppName]/

# Update documentation
# - Add entry to [TASKS.md](TASKS.md)
# - Update [WORKLOG.md](WORKLOG.md)
# - Document any special requirements

6. Create Pull Request

git add CloudronPackages/[AppName]/
git add [TASKS.md](TASKS.md) [WORKLOG.md](WORKLOG.md)
git commit -m "Add [AppName] Cloudron package"
git push origin feature/package-[appname]
# Create PR to integration branch

🏷️ Git Workflow

Branch Strategy

• main: Stable, production-ready packages
• integration: Integration branch for testing multiple packages
• feature/package-[appname]: Individual application packaging
• hotfix/[appname]-[issue]: Critical fixes

Commit Convention

type(scope): description

feat(apache): add Apache HTTP Server package
fix(nginx): resolve configuration template issue
docs: update packaging workflow documentation
chore: update upstream source repositories

🛠️ Package Components

Each Cloudron package requires:

Required Files

• CloudronManifest.json: App metadata, resources, addons
• Dockerfile: Container build instructions
• start.sh: Application startup script
• [AppName]-BuildNotes.md: Build and deployment instructions

Optional Files

• nginx.conf: Web server configuration
• supervisord.conf: Process management
• config.yaml: Application configuration template
• logo.png: Application icon

Key Requirements

• Use cloudron/base:4.2.0 base image
• Follow /app/code (read-only) and /app/data (persistent) structure
• Integrate with Cloudron addons via environment variables
• Implement proper health checks and logging
• Security: no hardcoded secrets, proper permissions

🔧 Tools and Resources

Development Container

• Name: tsys-cloudron-packaging
• Purpose: Isolated development environment for all packaging work
• Mounted: Repository at /workspace
• Persistent: Survives across development sessions

AI Coding Assistants

• AGENT.md: Comprehensive guide for using OpenCode, Gemini CLI, and Claude
• GEMINI.md: → Symbolic link to AGENT.md
• CLAUDE.md: → Symbolic link to AGENT.md
• Usage: Accelerate development with AI-assisted packaging

Helper Scripts

• UpstreamVendor-Clone.sh: Clone all upstream repositories
• UpstreamVendor-Update.sh: Update existing checkouts
• Template Prompt: CloudronPackagePrompt.md

Cloudron Resources

• Official Packaging Tutorial
• Packaging Cheat Sheet
• Cloudron Base Image

📊 Progress Tracking

• Overall Progress: See TASKS.md
• Daily Progress: See WORKLOG.md
• Strategy & Roadmap: See PLAN.md

Current Status

• ✅ Repository structure established
• ✅ Development workflow documented
• ✅ Packaging container ready
• ✅ Template and examples available
• 🚧 Individual application packaging in progress

🤝 Contributing

For KNEL Team Members

1. Review PLAN.md for current priorities
2. Check TASKS.md for available applications
3. Follow the packaging workflow above
4. Update documentation as you work
5. Create feature branches for each application

Code Review Checklist

• Dockerfile follows Cloudron conventions
• All required files present and properly configured
• Health checks implemented
• Logging configured to stdout/stderr
• Security best practices followed
• Documentation updated
• Build notes include testing steps

🐛 Troubleshooting

Common Issues

• Container won't start: Check logs with cloudron logs --app [appname]
• Database connection fails: Verify addon environment variables
• Static files not served: Check nginx configuration and file permissions
• Health check fails: Verify health check endpoint returns 200 OK

Getting Help

• Check build notes in CloudronPackages/[AppName]/
• Review Cloudron documentation
• Examine working examples (EasyGate, InvenTree)
• Use cloudron debug --app [appname] for interactive debugging

📝 License

See LICENSE file for details.

---

Last Updated: 2025-01-04
Maintainers: KNEL/TSYS Development Team