From 1c9efad0cf91b89c0ab4895c7321f71522521a76 Mon Sep 17 00:00:00 2001
From: knoflook <michal.kern@disroot.org>
Date: Thu, 25 Nov 2021 16:44:40 +0100
Subject: [PATCH] add recipe structure description

---
 docs/recipe-structure.md | 50 ++++++++++++++++++++++++++++++++++++++++
 mkdocs.yml               |  2 ++
 2 files changed, 52 insertions(+)
 create mode 100644 docs/recipe-structure.md

diff --git a/docs/recipe-structure.md b/docs/recipe-structure.md
new file mode 100644
index 0000000..0c96a7b
--- /dev/null
+++ b/docs/recipe-structure.md
@@ -0,0 +1,50 @@
+---
+title: Recipe structure
+---
+
+A recipe is a git repository that contains instructions for creating stacks that abra can read and interpret. You'll see a couple of files there:
+
+- [compose.yml](#composeyml) (required!)
+- [.env.sample](#envsample) (required!)
+- [abra.sh](#abrash)
+- [entrypoint.sh](#entrypointsh)
+- [other compose files](#other-compose-files)
+- [other files](#other-files)
+
+
+## compose.yml
+
+this is a [compose specification](https://compose-spec.io/) compliant file that contains a list of:
+
+- services
+- secrets
+- networks
+- volumes
+- configs
+
+that describe what is needed to run a stack. Whenever you deploy an app, abra reads this file to cook the stack.
+
+
+## .env.sample
+
+this file is a skeleton for environmental variables that should be adjusted by the user. Examples include: domain or php extention list. Whenever you create a new app with `abra app new` this file gets copied to the ~/.abra/servers/server-domain/app-name.env and when you run `abra app config` you're editing this file.
+
+
+## abra.sh
+
+`abra.sh` provides shell functions for running non-standard deploy, restore, rollback, backup and upgrade. This is only needed for some packages (such as nextcloud or wordpress)
+
+
+## entrypoint.sh
+
+after docker creates the filesystem and copies files into a new container it runs what's called an entrypoint. This is usually a shell script that exports some variables and runs the application. Sometimes the vendor entrypoint doesn't do everything that we need it to do. In that case you can write your own entrypoint, do whatever you need to do and then run the vendor entrypoint. For a simple example check [entrypoint.sh for croc](https://git.coopcloud.tech/coop-cloud/croc/src/commit/2f06e8aac52a3850d527434a26de0a242bea0c79/entrypoint.sh). In this case, croc needs the password to be exported as an environmental variable called `CROC_PASS`, and that is exactly what the entrypoint does before running vendor entrypoint. If you write your own entrypoint, it needs to be specified in the `config` section of compose.yml.
+
+
+## other compose files
+
+i.e. compose.smtp.yml. These are used to provide non-essential functionality such as (registration) e-mails or single sign on.
+
+
+## other files
+
+if you look at compose.yml (or compose.\*.yml) and see a `configs` section, that means this compose file is putting files in the container. This might be used for changing default (vendor) configuration, such as this [fpm-tune.ini file](https://git.coopcloud.tech/coop-cloud/nextcloud/src/commit/28425b6138603067021757de28c639ad464e9cf8/fpm-tune.ini) used to adjust php-fpm. 
diff --git a/mkdocs.yml b/mkdocs.yml
index d9b5df5..af61a2c 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -53,6 +53,8 @@ nav:
       - Roll an app back to a previous version: rollback.md
       - Running abra on the server: server-side.md
   - Glossary: glossary.md
+  - Under the hood:
+      - Recipe structure: recipe-structure.md
   - Strategy: strategy.md
   - Bike map: bikemap.md
   - Troubleshooting: troubleshooting.md