# 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
   ./run/dev.sh python --version
   ```
2. Enter an interactive devtools shell so every command runs inside Docker:
   ```bash
   ./run/dev.sh bash --login
   ```
3. Implement application-specific build steps in `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
./run/dev.sh python 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
./run/dev.sh bash --login

# inside the container
python scripts/new_app.py --slug apache-apisix
python scripts/new_app.py --force
python scripts/lint_repo.py --slug apache-apisix --strict
python scripts/generate_status.py --preserve-timestamp
```

Non-interactive equivalents:

```bash
./run/dev.sh python scripts/new_app.py --slug apache-apisix
./run/dev.sh python scripts/new_app.py --force
./run/dev.sh python scripts/lint_repo.py --slug apache-apisix --strict
./run/dev.sh python scripts/generate_status.py --preserve-timestamp
```

## Using the packager container

Open the Cloudron packaging environment via:

```bash
./run/packager.sh
```

Pass `BUILD=1` to rebuild the image before launching (`BUILD=1 ./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
./run/dev.sh python scripts/new_app.py --force           # regenerate entire catalog
./run/dev.sh python 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 `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`).