docs: comprehensive documentation and workflow overhaul
Create complete project documentation suite for 56-application Cloudron packaging initiative: New Documentation Files: - README.md: Comprehensive project overview with quick start guide - PLAN.md: Strategic roadmap for packaging across 2025 with 4-phase approach - TASKS.md: Detailed task list with 56 applications prioritized in 4 tiers - WORKLOG.md: Progress tracking with daily logs and development insights - GIT_WORKFLOW.md: Complete branching strategy and commit standards Enhanced Existing Documentation: - CloudronPackages/README.md: Enhanced package directory with usage instructions - CloudronPackagingWorkspace/README.md: Comprehensive workspace development guide Key Features: - Established feature → integration → master git workflow - Containerized development environment with tsys-cloudron-packaging - 4-tier priority system focusing on business-critical applications first - Quality standards and testing procedures for all packages - Team coordination tools for parallel development This foundation supports systematic packaging of all 56 applications with proper quality control, progress tracking, and team scalability. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
230
README.md
Normal file
230
README.md
Normal file
@@ -0,0 +1,230 @@
|
||||
# KNEL Production Containers - Cloudron Packaging Repository
|
||||
|
||||
This repository contains the infrastructure and tooling for packaging applications for [Cloudron](https://cloudron.io), 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 # This file
|
||||
├── PLAN.md # Overall packaging strategy and roadmap
|
||||
├── TASKS.md # Application checklist and status
|
||||
├── WORKLOG.md # Development progress log
|
||||
├── .gitignore # Git exclusions for workspace
|
||||
│
|
||||
├── CloudronPackages/ # ✅ Final tested packages (tracked in git)
|
||||
│ ├── PackageTemplate/ # Template and LLM prompts
|
||||
│ ├── EasyGate/ # Completed packages
|
||||
│ └── [AppName]/ # Individual app packages
|
||||
│
|
||||
├── CloudronPackagingWorkspace/ # 🚧 Development workspace
|
||||
│ ├── Docker/ (gitignored) # ~100 cloned upstream repositories
|
||||
│ ├── NonDocker/ (gitignored) # Non-Docker applications
|
||||
│ ├── UpstreamVendor-Clone.sh # Script to clone upstream sources
|
||||
│ └── UpstreamVendor-Update.sh # Script to update upstream sources
|
||||
│
|
||||
├── KNEL-Cloudron/ # 🏢 KNEL-specific deployment configs
|
||||
└── 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
git checkout -b feature/package-[appname]
|
||||
```
|
||||
|
||||
### 3. Package Development
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# Move to final location
|
||||
mv /workspace/[appname]_package_new ./CloudronPackages/[AppName]/
|
||||
|
||||
# Update documentation
|
||||
# - Add entry to TASKS.md
|
||||
# - Update WORKLOG.md
|
||||
# - Document any special requirements
|
||||
```
|
||||
|
||||
### 6. Create Pull Request
|
||||
```bash
|
||||
git add CloudronPackages/[AppName]/
|
||||
git add TASKS.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
|
||||
- **`master`**: 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
|
||||
|
||||
### Helper Scripts
|
||||
- **`UpstreamVendor-Clone.sh`**: Clone all upstream repositories
|
||||
- **`UpstreamVendor-Update.sh`**: Update existing checkouts
|
||||
- **Template Prompt**: `CloudronPackages/PackageTemplate/CloudronPackagePrompt.md`
|
||||
|
||||
### Cloudron Resources
|
||||
- [Official Packaging Tutorial](https://docs.cloudron.io/packaging/tutorial/)
|
||||
- [Packaging Cheat Sheet](https://docs.cloudron.io/packaging/cheat-sheet/)
|
||||
- [Cloudron Base Image](https://hub.docker.com/r/cloudron/base)
|
||||
|
||||
## 📊 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](LICENSE) file for details.
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-04
|
||||
**Maintainers**: KNEL/TSYS Development Team
|
||||
Reference in New Issue
Block a user