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.

No Host Pollution (containers only)

• Host requirements: docker, git (and optionally tea). Nothing else.
• All packaging work runs inside the packaging container. Do not install build tools on the host.
• Use the scripts provided:
  • scripts/packaging-up.sh – build/run the packaging container (mounts repo, docker socket)
  • scripts/packaging-enter.sh – open a shell inside the container
  • scripts/packaging-exec.sh <cmd> – run a command inside the container
  • scripts/workspace-clone.sh – run upstream clone inside the container
  • scripts/workspace-update.sh – run upstream update inside the container

The container image includes Docker CLI and Cloudron CLI, and accesses the host Docker via /var/run/docker.sock.

Quick start:

# Start container
scripts/packaging-up.sh

# Enter container shell
scripts/packaging-enter.sh

# Clone upstreams inside container
scripts/workspace-clone.sh

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 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 file for details.

---

Last Updated: 2025-01-04
Maintainers: KNEL/TSYS Development Team