# recipe

reusable groups of steps

A recipe is a named group of steps that you can use again, with its own variables, templates, and files.

## Files

A recipe is a directory in recipes/ with a recipe.yaml, and optional templates/ and files/ directories. Or it is a key in recipes of winch.yaml, without templates or files. winch loads every recipe for every command, also a recipe that no pipeline uses.

## Names

A recipe name has lowercase letters, digits, and \_. It can be the name of a module.

## Running a recipe

A step runs a recipe with recipe: \<name\>. A recipe step has only name, recipe, vars, and when. A recipe runs at most once per host in a run. Two stages can run the same recipe when their hosts do not overlap. A recipe cannot run another recipe.

## Templates and files

template reads from the templates/ directory of the recipe, and source from files/. Paths can name subdirectories. A template file uses the language of !tpl. Run winch doc templates.

## Keys

| Key | Type | Default | Meaning |
| --- | --- | --- | --- |
| [`require`](#recipe.require) | list of expressions | - | conditions on facts |
| [`vars`](#recipe.vars) | map | - | defaults of the recipe's own variables |
| [`steps`](#recipe.steps) | list of steps | required | module steps, in order |
| [`handlers`](#recipe.handlers) | map of lists of steps | - | steps that run after a change |

### `recipe.require` {#recipe.require}

list of expressions

Conditions on facts, each an !expr. Every host where the recipe runs in the pipeline meets all of them, or it fails at plan. They see only facts.

### `recipe.vars` {#recipe.vars}

map

Defaults of the recipe's own variables. Their names start with the recipe name and \_.

### `recipe.steps` {#recipe.steps}

list of steps, required

Module steps, in order. A recipe cannot run another recipe.

### `recipe.handlers` {#recipe.handlers}

map of lists of steps

Steps that run after a change. They run after the last step of the recipe, when a step notified them. Run winch doc handlers.

## Example

```
# recipes/nginx/recipe.yaml
require:
  - !expr facts.os.id in ["debian", "ubuntu"]
vars:
  nginx_port: 80
steps:
  - pkg:
      name: nginx
  - name: Configure the site
    file:
      path: /etc/nginx/sites-enabled/default
      template: site.tmpl
      validate: nginx -t
    notify: reload
  - service:
      name: nginx
      running: true
      enabled: true
handlers:
  reload:
    - service:
        name: nginx
        reloaded: true

# recipes/nginx/templates/site.tmpl
server {
    listen {{ .vars.nginx_port }};
}

# winch.yaml
name: acme
hosts:
  web1.acme.com: {}
steps:
  - recipe: nginx
    vars:
      nginx_port: 8080
```