autonomic-bot
f283a371bb
Sanitized single-commit public mirror of recipe-maintainer. - Removed test-ssh/.testenv (live creds); added test-ssh/.testenv.example placeholders. - Removed plans/ and planned-updates/ (deployment-planning docs) so no client/ deployment domains appear in the public repo. - All other secret stores were already gitignored. - docs.coopcloud.tech retained as a submodule (public upstream).
121 lines
6.3 KiB
Markdown
121 lines
6.3 KiB
Markdown
---
|
|
description: Review a recipe for Co-op Cloud best practices
|
|
argument-hint: <recipe-name>
|
|
allowed-tools: [Bash, Read, Write, Glob, Grep, WebFetch, WebSearch]
|
|
---
|
|
|
|
# Recipe Review
|
|
|
|
Review a Co-op Cloud recipe against best practices and suggest improvements. This performs a thorough audit of the recipe's configuration, security, and operational readiness.
|
|
|
|
The recipe name is: $ARGUMENTS
|
|
|
|
Read and follow the instructions in `.claude/commands/includes/logging.md`.
|
|
Read and follow the instructions in `.claude/commands/includes/guidelines.md`.
|
|
|
|
## Steps
|
|
|
|
1. **Fetch the recipe** — check for uncommitted local changes first (see guidelines). If clean, run `abra recipe fetch $ARGUMENTS --force`. If there are local changes, skip the fetch and note that you're using the local checkout.
|
|
The recipe lives at `~/.abra/recipes/$ARGUMENTS/`.
|
|
|
|
2. **Read all recipe files** — read every file in the recipe directory:
|
|
- `compose.yml` (and any `compose.*.yml` overlay files)
|
|
- `.env.sample`
|
|
- `abra.sh`
|
|
- `README.md`
|
|
- Any config templates (`.tmpl`, `.conf`, `.ini`, `.js`, etc.)
|
|
- Any entrypoint scripts (`entrypoint*.sh`)
|
|
- `release/` directory contents (if present)
|
|
- `MAINTENANCE.md` (if present)
|
|
|
|
3. **Run the linter** (if available):
|
|
```
|
|
abra recipe lint $ARGUMENTS
|
|
```
|
|
Note any warnings or errors.
|
|
|
|
4. **Check the recipe against each best practice area below.** For each area, note whether the recipe follows the practice, partially follows it, or is missing it entirely. Suggest specific fixes where applicable.
|
|
|
|
### Checklist
|
|
|
|
#### Compose structure
|
|
- [ ] Uses compose version `3.8`
|
|
- [ ] Services use named volumes (not bind mounts)
|
|
- [ ] No `ports:` definitions — routing is handled by Traefik labels
|
|
- [ ] No `env_file:` directives — environment is managed by abra
|
|
- [ ] Internal services (databases, caches) are on an `internal` network, not `proxy`
|
|
- [ ] The main web-facing service is on both `proxy` (external) and an internal network
|
|
|
|
#### Version label
|
|
- [ ] The `app` service has a `coop-cloud.${STACK_NAME}.version` deploy label
|
|
- [ ] The version follows the `X.Y.Z+upstream_version` format
|
|
|
|
#### Traefik labels
|
|
- [ ] `traefik.enable=true` on the web-facing service
|
|
- [ ] `traefik.http.routers.${STACK_NAME}.rule=Host(...)` is set
|
|
- [ ] `traefik.http.routers.${STACK_NAME}.tls=true` or `.tls.certresolver` is set
|
|
- [ ] `traefik.http.routers.${STACK_NAME}.entrypoints=web-secure` is set
|
|
- [ ] Traefik network is specified: `traefik.docker.network=proxy`
|
|
|
|
#### Deploy configuration
|
|
- [ ] `restart_policy` is configured (ideally with `max_attempts` to prevent infinite restarts)
|
|
- [ ] `update_config` with `failure_action: rollback` and `order: start-first` (recommended)
|
|
- [ ] `rollback_config` with `order: start-first` (recommended)
|
|
|
|
#### Healthchecks
|
|
- [ ] At least one service has a healthcheck defined
|
|
- [ ] Database/cache services have appropriate healthchecks (e.g. `redis-cli ping`, `pg_isready`)
|
|
- [ ] If healthchecks are absent, note this as an improvement area
|
|
|
|
#### Backups
|
|
|
|
Consult the README of the `backup-bot-two` recipe (`~/.abra/recipes/backup-bot-two/README.md`) for details on how to configure backup labels in Co-op Cloud recipes. Fetch it first if needed (`abra recipe fetch backup-bot-two`).
|
|
|
|
- [ ] `backupbot.backup=true` label is present on each service that has volumes to back up (can be on multiple services)
|
|
- [ ] By default all volumes on a labelled service are backed up — only use `backupbot.backup.volumes.<name>.path` or `backupbot.backup.volumes.<name>: false` when you need to limit or exclude specific volumes
|
|
- [ ] For database services: `backupbot.backup.pre-hook` dumps the database, `backupbot.restore.post-hook` restores it
|
|
- [ ] If backups are not configured, suggest adding `backupbot.backup` labels based on the backup-bot-two README
|
|
|
|
#### Secrets
|
|
- [ ] Sensitive values (passwords, API keys, tokens) use Docker secrets, not plain-text env vars
|
|
- [ ] Secret names are < 12 characters (to avoid the 64-char Docker limit after stack name + version are appended)
|
|
- [ ] `.env.sample` has `SECRET_*_VERSION=v1` entries for each secret
|
|
- [ ] `abra.sh` has secret generation hints (length, charset) if applicable
|
|
|
|
#### Environment variables
|
|
- [ ] `.env.sample` exists with all required variables
|
|
- [ ] Optional env vars are commented out in `.env.sample`
|
|
- [ ] Domain templating uses `<recipe>.example.com` pattern (auto-replaced by `abra app new`)
|
|
- [ ] New/optional env vars in compose.yml use defaults: `${MY_VAR:-default_value}`
|
|
- [ ] `STACK_NAME` is exposed in `environment:` for any service that needs it in config templates
|
|
|
|
#### Config management
|
|
- [ ] If the recipe uses Docker configs, versions are exported in `abra.sh`
|
|
- [ ] Config naming is consistent through the chain: configs stanza name, `name:` interpolation, and `abra.sh` export
|
|
- [ ] Config templates use `template_driver: golang` when Go template interpolation is needed
|
|
- [ ] Secrets in templates accessed via `{{ secret "name" }}`, env vars via `{{ env "NAME" }}`
|
|
|
|
#### README metadata
|
|
- [ ] README has the `<!-- metadata -->` ... `<!-- endmetadata -->` section
|
|
- [ ] All fields are present: Category, Status, Image, Healthcheck, Backups, Email, Tests, SSO
|
|
- [ ] Scores are accurate and reflect the current state of the recipe
|
|
- [ ] At least one named maintainer is listed (required for "stable" status)
|
|
|
|
#### Optional features
|
|
- [ ] SMTP/email support via `compose.smtp.yml` (if the app can send email)
|
|
- [ ] SSO/OIDC support via `compose.oidc.yml` (if the app supports it)
|
|
- [ ] Release notes in `release/` directory for each version
|
|
|
|
#### Resource limits
|
|
- [ ] Consider whether `deploy.resources.limits` should be set (memory/CPU) to prevent OOM issues on shared servers
|
|
|
|
5. **Summarise the review** with three sections:
|
|
|
|
**What's good** — things the recipe already does well.
|
|
|
|
**Recommended fixes** — issues that should be addressed (missing backup config, missing healthchecks, security concerns, incorrect labels, etc.). For each, provide the specific change needed (ideally a code snippet showing what to add/change in compose.yml or other files).
|
|
|
|
**Nice-to-haves** — optional improvements that would raise the recipe's quality/status score (SMTP support, SSO, better deploy config, resource limits, etc.).
|
|
|
|
Update the README metadata scores if they don't reflect reality (e.g. if backups are configured but README says "No").
|