recipe-maintainer/.claude/commands/recipe-init.md

description, argument-hint, allowed-tools

description	argument-hint	allowed-tools
Create a new test instance and recipe-info for a recipe	<recipe-name>	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:

   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:

     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:

   name = "$ARGUMENTS"
   

   If the recipe has dependencies (e.g. requires keycloak or authentik for SSO), add:

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