KNEL/KNELProductionContainers
2
0
Fork 0
Code Pull Requests Actions Packages Releases Activity

docs: rewrite README for streamlined single-branch repo

Browse Source
This commit is contained in:
Charles N Wyble - admin
2025-09-12 14:11:22 -05:00
parent 0e98a63b99
commit 7a4748496c
1 changed files with 40 additions and 187 deletions
Download Patch File Download Diff File Expand all files Collapse all files

227
README.md
View File

@@ -1,203 +1,56 @@
# KNEL Production Containers - Cloudron Packaging Repository
# KNEL Production Containers (Streamlined)
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.
Single-branch, streamlined repository for container work at KNEL. The focus is Cloudron app packaging and a small set of non‑Cloudron artifacts. All work happens directly on `main`.
## 🏗️ Repository Structure
## Layout
```
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
```
- `CloudronPackages/`
- Empty scaffold for Cloudron app packages. Create a subfolder per app and add your packaging files there.
- Tracked with `.gitkeep` so the directory exists in a clean repo.
- `PackagingForCloudronWorkspace/`
- Helper scripts and a workspace for interacting with upstream sources.
- Subfolders `Docker/` and `NonDocker/` are ignored by git (see `.gitignore`).
- Scripts: `UpstreamVendor-Clone.sh`, `UpstreamVendor-Update.sh`.
- `NonCloudron/`
- Non‑Cloudron experiments and orchestration notes.
- `.gitignore`, `LICENSE`, `README.md`
## 🚀 Quick Start
## Workflow (single branch)
### Prerequisites
- Docker (for containerized packaging)
- Cloudron CLI: `npm install -g cloudron`
- Git access to upstream repositories
- Branching: use only `main`.
- Commit small, focused changes; push directly to `origin/main`.
- No integration/feature branch dance; avoid long‑lived branches.
### Setup Development Environment
```bash
# Clone this repository
git clone [repository-url]
cd KNELProductionContainers
## Add a new Cloudron package
# 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
1) Create the package folder
- `mkdir -p CloudronPackages/<AppName>`
# Install tools in container
docker exec tsys-cloudron-packaging sh -c "
apt-get update && apt-get install -y git curl build-essential nodejs npm
"
2) Add the required files
- `CloudronManifest.json` – app metadata and addon requirements
- `Dockerfile` – image build instructions (use cloudron/base as appropriate)
- `start.sh` – container entry script
- Optional: `nginx.conf`, `supervisord.conf`, `config.yaml`, `logo.png`, build notes
# Clone upstream application sources
chmod +x CloudronPackagingWorkspace/*.sh
./CloudronPackagingWorkspace/UpstreamVendor-Clone.sh
```
3) Build/test locally (example)
- `docker build -t <app>:dev CloudronPackages/<AppName>`
- `docker run --rm -p 8080:8080 <app>:dev`
## 📋 Packaging Workflow
4) Commit and push
- `git add CloudronPackages/<AppName>/`
- `git commit -m "feat(<app>): initial Cloudron package"`
- `git push origin main`
### 1. Choose Application
- Check [TASKS.md](TASKS.md) for priority applications
- Verify upstream source is available in [CloudronPackagingWorkspace/Docker/](CloudronPackagingWorkspace/Docker/)
## Packaging workspace tips
### 2. Create Feature Branch
```bash
# Start from integration branch (not main!)
git checkout integration
git pull origin integration
git checkout -b feature/package-[appname]
```
- The workspace under `PackagingForCloudronWorkspace/` is for local convenience and upstream sync.
- `Docker/` and `NonDocker/` inside that directory are intentionally gitignored to keep the repo slim.
- Keep scripts and minimal config tracked; keep large clones and build outputs out of git.
### 3. Package Development
```bash
# Work in the persistent container
docker exec -it tsys-cloudron-packaging bash
## Notes
# 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](TASKS.md)
# - Update [WORKLOG.md](WORKLOG.md)
# - Document any special requirements
```
### 6. Create Pull Request
```bash
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](AGENT.md)**: Comprehensive guide for using OpenCode, Gemini CLI, and Claude
- **[GEMINI.md](GEMINI.md)**: → Symbolic link to AGENT.md
- **[CLAUDE.md](CLAUDE.md)**: → Symbolic link to AGENT.md
- **Usage**: Accelerate development with AI-assisted packaging
### Helper Scripts
- **[UpstreamVendor-Clone.sh](CloudronPackagingWorkspace/UpstreamVendor-Clone.sh)**: Clone all upstream repositories
- **[UpstreamVendor-Update.sh](CloudronPackagingWorkspace/UpstreamVendor-Update.sh)**: Update existing checkouts
- **Template Prompt**: [CloudronPackagePrompt.md](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](TASKS.md)
- **Daily Progress**: See [WORKLOG.md](WORKLOG.md)
- **Strategy & Roadmap**: See [PLAN.md](PLAN.md)
### Current Status
- ✅ Repository structure established
- ✅ Development workflow documented
- ✅ Packaging container ready
- ✅ Template and examples available
- 🚧 Individual application packaging in progress
## 🤝 Contributing
- This repo was reset to a simplified structure; historical multi‑branch workflows and extensive docs were removed to reduce friction.
- If you need legacy materials, refer to your local history/tags or the remote history prior to this cleanup.
### For KNEL Team Members
1. Review [PLAN.md](PLAN.md) for current priorities
@@ -236,4 +89,4 @@ See [LICENSE](LICENSE) file for details.
---
**Last Updated**: 2025-01-04
**Maintainers**: KNEL/TSYS Development Team
**Maintainers**: KNEL/TSYS Development Team