add glossary

docs/glossary.md

@@ -0,0 +1,29 @@
+---
+title: glossary
+---
+
+abra-related words
+
+- recipe - a git repository with files describing to abra how to assemble an application
+- application - an instance of a recipe composed of one or more services and running as a docker stack
+- service - a single docker container that is a part of a stack, configured in compose.yml and .env files
+- deployment - the act of assembling a docker stack described by a recipe and application configuration
+
+
+docker-related words:
+
+- image - a template for creating containers, describing their file structure, installed binaries etc.
+- container - an instance of an image, running processes that are isolated from the host system
+- environment variables - variables passed from the shell to processes invoked by it. used for configuring services.
+- .env file - a file describing the contents of environmental variables
+- network - a virtual network created on the server machine used for communicating between services (containers). Any service can be plugged into more than one network, allowing for control over data sharing between them.
+- secret - docker uses those for securely storing data such as passwords. They are stored encrypted on disk and mounted inside the containers as files that can be read that contain the secret.
+- stack - one or more services (containers) running together to provide a functionality.
+- volume - a directory that can be mounted inside a docker container to store data. Because containers are meant to be non-changeable and disposable, any data that is supposed to not be lost between updates or restarts is stored in volumes.
+
+
+"mappings" between those concepts:
+
+- abra app = docker stack
+- abra recipe = set of docker images in `compose` format
+- abra service = docker stack service

docs/recipe-structure.md

@@ -1,50 +0,0 @@
----
-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. 

mkdocs.yml

@@ -52,8 +52,7 @@ nav:
       - Scale an app up to handle more traffic: scale.md
       - Roll an app back to a previous version: rollback.md
       - Running abra on the server: server-side.md
-  - Under the hood:
-      - Recipe structure: recipe-structure.md
+  - Glossary: glossary.md
   - Strategy: strategy.md
   - Bike map: bikemap.md
   - Troubleshooting: troubleshooting.md