Scaffold Cloudron packaging workspace and automation

docs/PACKAGING_GUIDE.md

@@ -0,0 +1,82 @@
+# Cloudron Packaging Playbook
+
+This repository standardises the workflow for building and maintaining Cloudron packages for the Known Element portfolio.
+
+## Reference workflow
+
+1. Generate a package scaffold from the shared template using `scripts/new_app.py`.
+2. Run all build, test, and release tasks inside the `docker/packager` container to avoid host pollution.
+3. Implement application-specific build steps in `apps/<slug>/Dockerfile` and configure the runtime via `start.sh`.
+4. Update `CloudronManifest.json` with accurate metadata, addons, ports, and health checks based on the upstream project.
+5. Build and test locally with the Cloudron CLI (`cloudron build`, `cloudron install --app <domain>`) inside the packaging container.
+6. Push the image to the Cloudron registry (`cloudron push`) and publish once happy with smoke-test coverage.
+
+## Cloudron packaging essentials
+
+- **Base image**: Start from `cloudron/base:<version>` and add only the dependencies the app requires.
+- **CloudronManifest**: The manifest declares metadata, exposed ports, resource limits, addons (databases, object storage, email), and health checks. Always keep the `id` stable since it uniquely identifies the package inside Cloudron ecosystems.
+- **Start script**: Use `start.sh` to render configuration from environment variables and launch the primary process under the `cloudron` user.
+- **Tests**: Provide smoke tests in `test/` that Cloudron can run via `cloudron build --test`.
+- **Updates**: Bump the manifest `version`, document the change in `changelog`, and rebuild when upstream releases.
+
+## Repository linting
+
+Run the scaffold lint checks after editing an app to catch placeholder artefacts:
+
+```bash
+python3 scripts/lint_repo.py
+```
+
+Set `CLOUDRON_BASE` to override the expected base image version when needed.
+
+Use the Makefile shortcuts for common tasks:
+
+```bash
+make scaffold   # regenerate scaffolds from catalog
+make lint       # run repo lint checks
+make status     # refresh docs/APP_STATUS.md
+```
+
+Leverage the Gitea Actions workflow (`.gitea/workflows/ci.yml`) to enforce `make lint` and status generation on every push; instructions for runner setup live in `docs/CI_CD_GITEA.md`.
+
+Run the local harness via `./scripts/ci_local.sh` (or `make ci-local`) to replicate the CI pipeline without relying on a remote runner; see `docs/LOCAL_TESTING.md` for hook integration.
+
+## Using the packager container
+
+```bash
+# Build the helper image
+BUILD=1 scripts/run_packager.sh
+
+# Launch an interactive shell inside the packaging environment
+scripts/run_packager.sh
+```
+
+The container bundles the Cloudron CLI, Docker CLI, git, curl, and other tooling for reproducible builds. The host Docker socket is mounted so you can reuse local credentials while keeping the host clean.
+
+## Adding a new application
+
+```bash
+# Create the full scaffold for all catalog entries
+python3 scripts/new_app.py
+
+# Or generate a single skeleton
+python3 scripts/new_app.py --slug apache-apisix
+```
+
+Each scaffold contains:
+
+- `Dockerfile` – build instructions
+- `start.sh` – runtime entrypoint
+- `CloudronManifest.json` – metadata and permissions
+- `test/smoke.sh` – placeholder smoke test
+- `metadata.json` – issue and upstream bookkeeping
+- `README.md` – packaging checklist
+
+Update these files with the app-specific details, add upstream artefacts under `app/`, and commit the changes.
+
+## Repository etiquette
+
+- Document design decisions and manual steps in `docs/` or the per-app README.
+- Keep automation scripts idempotent; rerunning them should not damage uncommitted work.
+- Use semantic versioning in manifest files (`MAJOR.MINOR.PATCH`).
+