docs: rewrite README for streamlined single-branch repo
This commit is contained in:
225
README.md
225
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
|
||||||
|
|
||||||
```
|
- `CloudronPackages/`
|
||||||
KNELProductionContainers/
|
- Empty scaffold for Cloudron app packages. Create a subfolder per app and add your packaging files there.
|
||||||
├── [README.md](README.md) # This file
|
- Tracked with `.gitkeep` so the directory exists in a clean repo.
|
||||||
├── [PLAN.md](PLAN.md) # Overall packaging strategy and roadmap
|
- `PackagingForCloudronWorkspace/`
|
||||||
├── [TASKS.md](TASKS.md) # Application checklist and status
|
- Helper scripts and a workspace for interacting with upstream sources.
|
||||||
├── [WORKLOG.md](WORKLOG.md) # Development progress log
|
- Subfolders `Docker/` and `NonDocker/` are ignored by git (see `.gitignore`).
|
||||||
├── [.gitignore](.gitignore) # Git exclusions for workspace
|
- Scripts: `UpstreamVendor-Clone.sh`, `UpstreamVendor-Update.sh`.
|
||||||
│
|
- `NonCloudron/`
|
||||||
├── [CloudronPackages/](CloudronPackages/) # ✅ Final tested packages (tracked in git)
|
- Non‑Cloudron experiments and orchestration notes.
|
||||||
│ ├── [PackageTemplate/](CloudronPackages/PackageTemplate/) # Template and LLM prompts
|
- `.gitignore`, `LICENSE`, `README.md`
|
||||||
│ ├── [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
|
## Workflow (single branch)
|
||||||
|
|
||||||
### Prerequisites
|
- Branching: use only `main`.
|
||||||
- Docker (for containerized packaging)
|
- Commit small, focused changes; push directly to `origin/main`.
|
||||||
- Cloudron CLI: `npm install -g cloudron`
|
- No integration/feature branch dance; avoid long‑lived branches.
|
||||||
- Git access to upstream repositories
|
|
||||||
|
|
||||||
### Setup Development Environment
|
## Add a new Cloudron package
|
||||||
```bash
|
|
||||||
# Clone this repository
|
|
||||||
git clone [repository-url]
|
|
||||||
cd KNELProductionContainers
|
|
||||||
|
|
||||||
# Set up packaging container (persistent across sessions)
|
1) Create the package folder
|
||||||
docker run -d --name tsys-cloudron-packaging \
|
- `mkdir -p CloudronPackages/<AppName>`
|
||||||
-v $(pwd):/workspace \
|
|
||||||
-w /workspace \
|
|
||||||
python:3.11-slim tail -f /dev/null
|
|
||||||
|
|
||||||
# Install tools in container
|
2) Add the required files
|
||||||
docker exec tsys-cloudron-packaging sh -c "
|
- `CloudronManifest.json` – app metadata and addon requirements
|
||||||
apt-get update && apt-get install -y git curl build-essential nodejs npm
|
- `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
|
3) Build/test locally (example)
|
||||||
chmod +x CloudronPackagingWorkspace/*.sh
|
- `docker build -t <app>:dev CloudronPackages/<AppName>`
|
||||||
./CloudronPackagingWorkspace/UpstreamVendor-Clone.sh
|
- `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
|
## Packaging workspace tips
|
||||||
- Check [TASKS.md](TASKS.md) for priority applications
|
|
||||||
- Verify upstream source is available in [CloudronPackagingWorkspace/Docker/](CloudronPackagingWorkspace/Docker/)
|
|
||||||
|
|
||||||
### 2. Create Feature Branch
|
- The workspace under `PackagingForCloudronWorkspace/` is for local convenience and upstream sync.
|
||||||
```bash
|
- `Docker/` and `NonDocker/` inside that directory are intentionally gitignored to keep the repo slim.
|
||||||
# Start from integration branch (not main!)
|
- Keep scripts and minimal config tracked; keep large clones and build outputs out of git.
|
||||||
git checkout integration
|
|
||||||
git pull origin integration
|
|
||||||
git checkout -b feature/package-[appname]
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. Package Development
|
## Notes
|
||||||
```bash
|
|
||||||
# Work in the persistent container
|
|
||||||
docker exec -it tsys-cloudron-packaging bash
|
|
||||||
|
|
||||||
# Create package structure
|
- This repo was reset to a simplified structure; historical multi‑branch workflows and extensive docs were removed to reduce friction.
|
||||||
cd /workspace
|
- If you need legacy materials, refer to your local history/tags or the remote history prior to this cleanup.
|
||||||
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
|
|
||||||
|
|
||||||
### For KNEL Team Members
|
### For KNEL Team Members
|
||||||
1. Review [PLAN.md](PLAN.md) for current priorities
|
1. Review [PLAN.md](PLAN.md) for current priorities
|
||||||
|
|||||||
Reference in New Issue
Block a user