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