# KNEL Production Containers (Streamlined)

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`.

## Layout

- `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`

## Workflow (single branch)

- Branching: use only `main`.
- Commit small, focused changes; push directly to `origin/main`.
- No integration/feature branch dance; avoid long‑lived branches.

## Add a new Cloudron package

1) Create the package folder
- `mkdir -p CloudronPackages/<AppName>`

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

3) Build/test locally (example)
- `docker build -t <app>:dev CloudronPackages/<AppName>`
- `docker run --rm -p 8080:8080 <app>:dev`

4) Commit and push
- `git add CloudronPackages/<AppName>/`
- `git commit -m "feat(<app>): initial Cloudron package"`
- `git push origin main`

## Packaging workspace tips

- 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.

## Notes

- 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
2. Check [TASKS.md](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