diff --git a/README.md b/README.md index 9d0bb20..ea6caff 100644 --- a/README.md +++ b/README.md @@ -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/` -# 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 :dev CloudronPackages/` +- `docker run --rm -p 8080:8080 :dev` -## πŸ“‹ Packaging Workflow +4) Commit and push +- `git add CloudronPackages//` +- `git commit -m "feat(): 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 \ No newline at end of file +**Maintainers**: KNEL/TSYS Development Team