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).
106 lines
6.9 KiB
Markdown
106 lines
6.9 KiB
Markdown
---
|
|
description: Create a new test instance and recipe-info for a recipe
|
|
argument-hint: <recipe-name>
|
|
allowed-tools: [Bash, Read, Write, Glob, Grep, WebFetch, WebSearch]
|
|
---
|
|
|
|
# Recipe Init
|
|
|
|
Bootstrap everything needed to start working with a Co-op Cloud recipe: fetch it, create a test instance, set up the `recipe-info/` directory with upstream info and tests, and deploy.
|
|
|
|
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. **Resolve the active instance** — run `python3 scripts/get_test_instance.py` to get SERVER and INSTANCE. Use these values throughout (not hardcoded instance names).
|
|
|
|
2. **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.
|
|
|
|
3. **Read the recipe's compose.yml** to identify images and services. The recipe lives at `~/.abra/recipes/$ARGUMENTS/compose.yml`.
|
|
|
|
4. **Read the recipe's README** at `~/.abra/recipes/$ARGUMENTS/README.md` (if it exists):
|
|
- Look for any required initial configuration steps beyond what `abra app new` handles (e.g. manual env vars, external dependencies, DNS records, post-deploy setup commands, required third-party accounts or API keys).
|
|
- Note any documented setup instructions, caveats, or prerequisites.
|
|
- If the README mentions configuration that needs operator action, include it in the summary at the end and set the relevant env vars in the `abra app new` step or in the app's env file if possible.
|
|
|
|
5. **Identify all required domains** and ask the user to set up DNS:
|
|
- The primary domain is always `$ARGUMENTS.<DOMAIN_SUFFIX>`.
|
|
- Check compose.yml and `.env.sample` for additional domain variables (e.g. `SANDBOX_DOMAIN`, `EXTRA_DOMAINS`). For each additional domain, propose a subdomain following the pattern `<purpose>-$ARGUMENTS.<DOMAIN_SUFFIX>`.
|
|
- Present the full list of domains to the user and tell them each one needs a DNS A/CNAME record pointing to the test server.
|
|
- **Stop and wait for the user to confirm the DNS records are in place** before continuing. TLS certificate provisioning (via Let's Encrypt / Traefik) will fail if the domains don't resolve to the server.
|
|
|
|
6. **Create the test app instance** via:
|
|
```
|
|
abra app new $ARGUMENTS --server <SERVER> --domain $ARGUMENTS.<DOMAIN_SUFFIX> --no-input
|
|
```
|
|
- Do NOT pass `--secrets` here — secrets are generated separately in step 7 so we can capture them.
|
|
- `--no-input` for non-interactive mode.
|
|
- If the app already exists (command errors with an "already exists" message), note that and skip creation.
|
|
- If the README (step 4) mentioned required env vars or configuration, set them in the app's env file before deploying. The env file is at `~/.abra/servers/<SERVER>/$ARGUMENTS.<DOMAIN_SUFFIX>.env`.
|
|
|
|
7. **Generate and save secrets** — Generate secrets separately so the machine-readable output can be captured and saved:
|
|
```bash
|
|
abra app secret generate $ARGUMENTS.<DOMAIN_SUFFIX> --all -m --no-input
|
|
```
|
|
- The `-m` flag produces machine-readable output with the secret names and values.
|
|
- Capture this output and save it to `recipe-info/testsecrets/$ARGUMENTS.<DOMAIN_SUFFIX>`. Create the `testsecrets/` directory if it doesn't exist.
|
|
- Each line should be in `name=value` format.
|
|
- **Fallback**: If secrets were already generated (e.g. via a previous `abra app new --secrets`) and the values weren't saved, you can read them from the running container after deployment:
|
|
```bash
|
|
ssh <SERVER> 'CID=$(docker ps -q -f name=<stack_prefix>_app); for f in $(docker exec $CID ls /run/secrets/); do echo "$f=$(docker exec $CID cat /run/secrets/$f)"; done'
|
|
```
|
|
|
|
8. **Create `recipe-info/$ARGUMENTS/recipe.toml`** with the content:
|
|
```toml
|
|
name = "$ARGUMENTS"
|
|
```
|
|
If the recipe has dependencies (e.g. requires keycloak or authentik for SSO), add:
|
|
```toml
|
|
[dependencies]
|
|
requires = ["keycloak"]
|
|
|
|
[sso]
|
|
provider = "keycloak"
|
|
setup_script = "setup/sso_integration.py"
|
|
```
|
|
|
|
9. **Create `recipe-info/$ARGUMENTS/upstream.md`** — Discover the upstream project info:
|
|
- Read compose.yml to identify all images used by the recipe.
|
|
- Search for GitHub repos and release pages for each image.
|
|
- Write upstream.md following the format in `recipe-info/hedgedoc/upstream.md` as a template.
|
|
|
|
10. **Create `recipe-info/$ARGUMENTS/setup.md`** (if it doesn't already exist) — Write a first-time setup guide based on the README and what you learned in steps 3-7:
|
|
- Use `recipe-info/hedgedoc/setup.md` as the template format.
|
|
- Use `<SERVER>`, `<DOMAIN_SUFFIX>` as placeholders (not hardcoded instance names) so the guide works on any instance.
|
|
- **Prerequisites**: DNS records needed, any external dependencies (e.g. "Keycloak must be deployed first").
|
|
- **Steps**: The exact `abra` commands to go from nothing to a working deployment — `abra app new`, `abra app secret generate`, any env file edits, `abra app deploy`, and any post-deploy commands (migrations, admin user creation, etc.).
|
|
- If the recipe needs SSO integration, add a step referencing the appropriate `setup_*_integration.py` script.
|
|
- If the README mentioned any special configuration, post-deploy hooks, or manual steps, include them.
|
|
- Keep it concise — this is a quick-reference runbook, not full documentation.
|
|
|
|
11. **Create `recipe-info/$ARGUMENTS/test.md`** — Write a test plan:
|
|
- Target URL: `https://$ARGUMENTS.<DOMAIN_SUFFIX>`
|
|
- List automated test scripts (at minimum, `health_check.py`).
|
|
- List manual verification steps (at minimum, open the URL in a browser and confirm it loads).
|
|
- If the README mentioned any post-deploy verification steps, include them in the manual checks.
|
|
|
|
12. **Create `recipe-info/$ARGUMENTS/tests/health_check.py`** — A basic health check script following the pattern in `recipe-info/hedgedoc/tests/health_check.py`:
|
|
- Use `utils.tests.helpers` for HTTP checks and domain resolution.
|
|
- Check for HTTP 200 at the instance URL.
|
|
|
|
13. **Deploy the app**:
|
|
```
|
|
abra app deploy $ARGUMENTS.<DOMAIN_SUFFIX> --chaos --force --no-input
|
|
```
|
|
- If the README mentioned any post-deploy setup commands (e.g. running migrations, creating an admin user), run them after deployment.
|
|
- If secrets weren't saved in step 7 (fallback case), read them from the running containers now and save to `recipe-info/testsecrets/`.
|
|
|
|
14. **Summarise** — Tell the user what was created and suggest next steps:
|
|
- Run `/recipe-test $ARGUMENTS` to verify the deployment.
|
|
- Run `/recipe-check $ARGUMENTS` to check for upgrades.
|
|
- Add more test scripts to `recipe-info/$ARGUMENTS/tests/`.
|
|
- If the README flagged any configuration that couldn't be automated (e.g. external API keys, DNS records, third-party accounts), list those as manual actions the user still needs to take.
|