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).
56 lines
2.5 KiB
Markdown
56 lines
2.5 KiB
Markdown
---
|
||
description: Guide for developing a new Co-op Cloud recipe from scratch
|
||
allowed-tools: [Read, Glob, Grep]
|
||
---
|
||
|
||
# New Recipe Development Guide
|
||
|
||
This guide walks through how to develop a new Co-op Cloud recipe from scratch using this toolkit.
|
||
|
||
## Step 1: Gather references
|
||
|
||
Download any relevant references into `references/` — upstream documentation, example Docker Compose files, configuration guides, environment variable docs, etc. The more context available, the better the recipe will be.
|
||
|
||
## Step 2: Study existing patterns
|
||
|
||
Before writing anything, consult these resources to understand how Co-op Cloud recipes are structured:
|
||
|
||
- **`docs.coopcloud.tech/`** — The Co-op Cloud documentation, especially the recipe structure and deployment conventions
|
||
- **`~/.abra/recipes/`** — Other existing recipes, particularly ones similar to the app you're packaging (e.g. if your app uses PostgreSQL, look at how other recipes handle it)
|
||
- **`learnings.md`** — Hard-won lessons about `abra` CLI quirks and operational patterns
|
||
|
||
## Step 3: Develop the recipe
|
||
|
||
Tell Claude to consult the references you downloaded, along with `docs.coopcloud.tech/`, relevant existing recipes in `~/.abra/recipes/`, and `learnings.md`, in order to develop the new recipe.
|
||
|
||
A recipe typically includes:
|
||
|
||
- **`compose.yml`** — Service definitions with Traefik labels, healthchecks, deploy config, secrets, and environment variables
|
||
- **`.env.sample`** — Default environment variable values
|
||
- **`README.md`** — Recipe metadata (category, status, upstream URL, etc.)
|
||
- **`abra.sh`** — Optional post-deploy hooks
|
||
|
||
## Step 4: Create tests
|
||
|
||
Tell Claude to create tests in `recipe-info/<recipe>/tests/` to verify the recipe works correctly. Tests should include:
|
||
|
||
- **Basic health tests** — Verify the app is reachable and responding
|
||
- **OIDC integration tests** — If the app supports OIDC/SSO (e.g. via Authentik or Keycloak), test that the integration works
|
||
- **1–2 application-specific tests** — Test core functionality specific to the app (e.g. can create a document, can upload a file, API responds correctly)
|
||
|
||
## Step 5: Deploy and iterate
|
||
|
||
Use the toolkit skills to deploy and test iteratively:
|
||
|
||
1. **`/recipe-deploy <name>`** — Deploy your local changes to the test server
|
||
2. **`/recipe-test <name>`** — Run the tests you created
|
||
3. Fix any issues, repeat until all tests pass
|
||
|
||
## Step 6: Review and tag
|
||
|
||
Once tests pass:
|
||
|
||
1. **`/recipe-review <name>`** — Audit against Co-op Cloud best practices
|
||
2. Fix any issues the review identifies
|
||
3. **`/recipe-new-tag <name>`** — Create the first version tag
|