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

📊 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

Review PLAN.md for current priorities
Check TASKS.md for available applications
Follow the packaging workflow above
Update documentation as you work
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