---
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.