118 lines
4.4 KiB
Markdown
118 lines
4.4 KiB
Markdown
# 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](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
|