96 lines
3.6 KiB
Markdown
96 lines
3.6 KiB
Markdown
# Cloudron Packaging Playbook
|
||
|
||
This repository standardises the workflow for building and maintaining Cloudron packages for the Known Element portfolio.
|
||
|
||
## Reference workflow
|
||
|
||
1. Build or refresh the devtools image when dependencies change:
|
||
```bash
|
||
./output/run/dev.sh python --version
|
||
```
|
||
2. Enter an interactive devtools shell so every command runs inside Docker:
|
||
```bash
|
||
./output/run/dev.sh bash --login
|
||
```
|
||
3. Implement application-specific build steps in `output/apps/<slug>/Dockerfile` and configure runtime behaviour through `start.sh`.
|
||
4. Update `CloudronManifest.json` with accurate metadata, addons, ports, and health checks.
|
||
5. Build and test using the devtools shell or one-off wrappers.
|
||
6. Push new images via the Cloudron packager shell when smoke tests pass.
|
||
|
||
## Cloudron packaging essentials
|
||
|
||
- **Base image:** The runtime stage **must** derive from `cloudron/base:<version>`; use a dedicated builder stage to compile artefacts and copy only what you need.
|
||
- **CloudronManifest:** Declare metadata, exposed ports, resource limits, addons, and health checks. Keep `id` stable and set realistic limits per app.
|
||
- **Start script:** Render configuration from environment variables and launch the primary process as `cloudron`.
|
||
- **Tests:** Provide smoke tests in `test/` so `cloudron build --test` can validate deployments.
|
||
- **Updates:** Bump the manifest `version`, document the change in `changelog`, and rebuild for upstream releases.
|
||
|
||
## Repository linting
|
||
|
||
Run lint checks entirely through the devtools wrapper:
|
||
|
||
```bash
|
||
./output/run/dev.sh python output/scripts/lint_repo.py --slug apache-apisix --strict
|
||
```
|
||
|
||
Add `--base-prefix` if you intentionally change the final base image prefix.
|
||
|
||
## Common workflows
|
||
|
||
Interactive session (recommended while iterating):
|
||
|
||
```bash
|
||
./output/run/dev.sh bash --login
|
||
|
||
# inside the container
|
||
python output/scripts/new_app.py --slug apache-apisix
|
||
python output/scripts/new_app.py --force
|
||
python output/scripts/lint_repo.py --slug apache-apisix --strict
|
||
python output/scripts/generate_status.py --preserve-timestamp
|
||
```
|
||
|
||
Non-interactive equivalents:
|
||
|
||
```bash
|
||
./output/run/dev.sh python output/scripts/new_app.py --slug apache-apisix
|
||
./output/run/dev.sh python output/scripts/new_app.py --force
|
||
./output/run/dev.sh python output/scripts/lint_repo.py --slug apache-apisix --strict
|
||
./output/run/dev.sh python output/scripts/generate_status.py --preserve-timestamp
|
||
```
|
||
|
||
## Using the packager container
|
||
|
||
Open the Cloudron packaging environment via:
|
||
|
||
```bash
|
||
./output/run/packager.sh
|
||
```
|
||
|
||
Pass `BUILD=1` to rebuild the image before launching (`BUILD=1 ./output/run/packager.sh`). Use this shell for `cloudron build`, `cloudron install`, and `cloudron push` operations.
|
||
|
||
## Adding a new application
|
||
|
||
Generate scaffolds with the devtools wrapper:
|
||
|
||
```bash
|
||
./output/run/dev.sh python output/scripts/new_app.py --force # regenerate entire catalog
|
||
./output/run/dev.sh python output/scripts/new_app.py --slug apache-apisix
|
||
```
|
||
|
||
Each scaffold contains:
|
||
|
||
- `Dockerfile` – multi-stage 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 app-specific details, add artefacts under `app/`, and commit the changes.
|
||
|
||
## Repository etiquette
|
||
|
||
- Document design decisions and manual steps in `output/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`).
|