70 lines
4.7 KiB
Markdown
70 lines
4.7 KiB
Markdown
# Agent Operating Guide (Project-wide)
|
||
|
||
Scope: This file applies to the entire repository. It defines how assistants and automation must work here.
|
||
|
||
## Purpose
|
||
Package ~100 free/libre/open-source applications as Cloudron apps with a fast, container-only workflow and a minimal, single-branch repo.
|
||
|
||
## Golden Rules
|
||
- Single branch: use only `main`. Do not create feature branches unless explicitly requested.
|
||
- No host pollution: never install packages or tools on the host. The only required host tools are `docker`, `git` (and optionally `tea`).
|
||
- Containers only: all build, test, lint, and packaging commands must run inside the packaging container.
|
||
- Do not push to remote without approval: never run `git push` for a package change until it has been validated and explicitly approved by the maintainer.
|
||
- Keep repo slim: do not commit upstream source trees or build artefacts. Only commit package files under `CloudronPackages/<AppName>/`, small helper scripts, and minimal docs.
|
||
- Secrets: do not commit secrets or credentials. Use environment variables or Cloudron addons.
|
||
- Consistency: follow `.editorconfig`, `.gitattributes`, and `.gitignore`.
|
||
|
||
## Container-Only Workflow
|
||
- Packaging image: built from `docker/packaging/Dockerfile`.
|
||
- Control scripts (host-side wrappers):
|
||
- `scripts/packaging-up.sh` – build and start the packaging container; mounts repo at `/workspace` and `/var/run/docker.sock`.
|
||
- `scripts/packaging-enter.sh` – open a shell inside the container.
|
||
- `scripts/packaging-exec.sh <cmd>` – run any command inside the container.
|
||
- `scripts/workspace-clone.sh` – clone upstream repos (inside container).
|
||
- `scripts/workspace-update.sh` – update upstream repos (inside container).
|
||
- Never run package build/test outside the container. If a command needs to run, wrap it via `scripts/packaging-exec.sh`.
|
||
|
||
## Creating a New Package
|
||
- Scaffold from template using the helper:
|
||
- `scripts/new-package.sh <AppName> --id <com.example.app> --title "Title" --port <port> [--base <cloudron_base_tag>]`
|
||
- Edit `CloudronPackages/<AppName>/Dockerfile` and `start.sh` to run the app.
|
||
- Prefer prebuilt upstream releases over building toolchains in Docker to keep images small.
|
||
- Default Cloudron base image tag is `5.0.0`. Override with `--base` as needed.
|
||
|
||
## Validation Checklist (must pass before proposing push)
|
||
- Build succeeds inside the packaging container:
|
||
- `scripts/packaging-exec.sh "docker build -t <app>:dev CloudronPackages/<AppName>"`
|
||
- Run sanity check inside container:
|
||
- `scripts/packaging-exec.sh "docker run --rm -p <hp>:<hp> -v <app>-data:/app/data <app>:dev"`
|
||
- Health endpoint responds; logs show no fatal errors; app starts with least privilege.
|
||
- Manifest sanity: `CloudronManifest.json` has accurate `id`, `version`, `httpPort` or addon definitions, and `healthCheckPath`.
|
||
- No secrets or hard-coded credentials; proper ownership of `/app/data`.
|
||
- Image hygiene: no unnecessary build deps; minimal layers; correct exposed ports.
|
||
- Optional: `cloudron install --image <app>:dev` tested from inside the packaging container using `cloudron` CLI, if available.
|
||
|
||
## Approval Gate and Push Policy
|
||
- After validation, present a summary of what changed and the validation output to the maintainer.
|
||
- Only on explicit approval run `git push origin main` for the package commit(s).
|
||
- Never force-push unless explicitly instructed.
|
||
|
||
## Repository Hygiene
|
||
- Do not commit upstream repos. The directories `PackagingForCloudronWorkspace/Docker/` and `PackagingForCloudronWorkspace/NonDocker/` are gitignored on purpose.
|
||
- Keep package directories focused: `CloudronManifest.json`, `Dockerfile`, `start.sh`, and minimal config (e.g., `nginx.conf`, `supervisord.conf`, `config.yaml`, `logo.png`).
|
||
- Use LF line endings and 2-space indentation (see `.editorconfig`/`.gitattributes`).
|
||
|
||
## Networking & External Access
|
||
- All networked actions (git clones, docker pulls, downloads) must happen from within the packaging container.
|
||
- Host-level curl allowance: You MAY use `curl` on the host strictly for quick connectivity checks (e.g., verifying a URL or endpoint is reachable). Do not install any additional host packages beyond `docker`, `git` (and optionally `tea`).
|
||
- Do not attempt other host-level network configuration or host-level package installation.
|
||
|
||
## Commit Messages
|
||
- Use conventional, concise messages:
|
||
- `feat(<app>): ...` for new packages or features
|
||
- `fix(<app>): ...` for fixes
|
||
- `chore(...)`, `docs(...)` for non-functional changes
|
||
- Avoid large, mixed commits; keep changes scoped to an app.
|
||
|
||
## When in Doubt
|
||
- Ask for maintainer guidance before introducing new tools, dependencies, or changing global structure.
|
||
- Default to safer, smaller changes and explicit approval before pushing.
|