Scaffold Cloudron packaging workspace
This commit is contained in:
@@ -4,79 +4,92 @@ This repository standardises the workflow for building and maintaining Cloudron
|
||||
|
||||
## 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.
|
||||
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**: 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.
|
||||
- **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 the scaffold lint checks after editing an app to catch placeholder artefacts:
|
||||
Run lint checks entirely through the devtools wrapper:
|
||||
|
||||
```bash
|
||||
python3 scripts/lint_repo.py
|
||||
./run/dev.sh python scripts/lint_repo.py --slug apache-apisix --strict
|
||||
```
|
||||
|
||||
Set `CLOUDRON_BASE` to override the expected base image version when needed.
|
||||
Add `--base-prefix` if you intentionally change the final base image prefix.
|
||||
|
||||
Use the Makefile shortcuts for common tasks:
|
||||
## Common workflows
|
||||
|
||||
Interactive session (recommended while iterating):
|
||||
|
||||
```bash
|
||||
make scaffold # regenerate scaffolds from catalog
|
||||
make lint # run repo lint checks
|
||||
make status # refresh docs/APP_STATUS.md
|
||||
./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
|
||||
```
|
||||
|
||||
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`.
|
||||
Non-interactive equivalents:
|
||||
|
||||
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.
|
||||
```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
|
||||
|
||||
```bash
|
||||
# Build the helper image
|
||||
BUILD=1 scripts/run_packager.sh
|
||||
Open the Cloudron packaging environment via:
|
||||
|
||||
# Launch an interactive shell inside the packaging environment
|
||||
scripts/run_packager.sh
|
||||
```bash
|
||||
./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.
|
||||
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
|
||||
|
||||
```bash
|
||||
# Create the full scaffold for all catalog entries
|
||||
python3 scripts/new_app.py
|
||||
Generate scaffolds with the devtools wrapper:
|
||||
|
||||
# Or generate a single skeleton
|
||||
python3 scripts/new_app.py --slug apache-apisix
|
||||
```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` – build instructions
|
||||
- `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 the app-specific details, add upstream artefacts under `app/`, and commit the changes.
|
||||
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`).
|
||||
|
||||
|
||||
Reference in New Issue
Block a user