docs: new ssh consolidation changes

See coop-cloud/abra#255

Dockerfile

@@ -1,4 +1,4 @@
-FROM squidfunk/mkdocs-material:9.0.11
+FROM squidfunk/mkdocs-material:9.0.12
 
 EXPOSE 8000
 

docs/abra/install.md

@@ -2,6 +2,10 @@
 title: Install
 ---
 
+!!! warning
+
+    We've seen reports that `abra` under [WSL](https://learn.microsoft.com/en-us/windows/wsl/about) doesn't work due to an underlying bug in Docker context handling. See [`coop-cloud/organising#406`](https://git.coopcloud.tech/coop-cloud/organising/issues/406) and [`docker/for-win#13180`](https://github.com/docker/for-win/issues/13180) for more.
+
 ## Stable release
 
 ```

docs/abra/upgrade.md

@@ -18,6 +18,35 @@ abra upgrade --rc
 
 ## Migration guides
 
+### `0.6.x-beta` -> `0.7.x-beta`
+
+> **ALERTA, ALERTA**: this is currently only available via the release
+> candidate channel, using `abra upgrade --rc`. There has been a lot of churn
+> and we're being cautious about releasing this one. Please help us test! We're
+> currently on `0.7.0-rc2-beta`.
+
+- `kadabra`, the app auto-updater is available for general alpha testing! See [these docs](https://docs.coopcloud.tech/operators/tutorial/#automatic-upgrades) for how to get started. Binaries can be found [here](https://git.coopcloud.tech/coop-cloud/abra/releases/tag/0.7.0-rc2-beta).
+
+- **ALERTA, ALERTA**, security related issue: all `$domain.env` env vars are now exposed to the deployment via the `app` service container. Each `FOO=BAR` is exported within the context of the container. If you have any privately committed secrets in your `.env` files, please migrate them to the `secrets: ...` configuration in the recipe. This change was made to facilitate tooling which can support auto-upgrading of apps in a deployment.
+
+- `abra` can no longer install Docker, initialise swarm mode and the proxy network. It will check if a Docker install exists and is in swarm mode or not and error out accordingly. We leave the provisioning to tools that are designed for that and reduce the command-line surface that we have to maintain going forward.
+
+- `abra server add <host> <args>` 👉 `abra server add <host>`. We have finally removed the custom SSH handling code and now solely rely on invoke `/usr/bin/ssh` directly and reading from the `~/.ssh/config`. The `<host>` argument should correspond to a `Host <host>` entry in your `~/.ssh/config` or in an `Include <file>` statement (hosts are retrieved via `ssh -G <host>`). This means "how does `abra` interact with SSH is 1) do you have an `~/.ssh/config` entry for `<host>` 2) can you `ssh <host>` successfully? 3) there is no 3. It's an easier mental model and also the way `abra-bash` works, hence, less weird obscure errors. `<host>` being public a domain name is still required.
+
+- `abra` no longer tries to do the TOFU host key verification prompt. We follow the praxis of the Docker CLI and just give up when host keys are not validated. We leave it to folks to SSH in and verify themselves.
+
+- On the way to [`kadabra`](https://git.coopcloud.tech/coop-cloud/abra/pulls/268), several changes regarding labelling deployments have been merged in this release. This will allow tooling to understand a deployment without having the context of a `~/.abra/...` configuration. This will pave the way for server-side tooling, like `kadabra` which can help operators with different kinds of maintenance tasks.
+
+- Welcome `abra recipe fetch`, which helps retrieve a recipe repository to your local work-station.
+
+- Also say hello to `abra app services <domain>`, which lists the in-deployment service names and corresponding image, e.g. `foo_example_com`.
+
+- Digests have been removed from the catalogue generation.
+
+- Backup files generated by `abra` have a much more human-friendly format.
+
+- Linting for domains is disabled when no `DOMAIN=...` is discovered in the `$odmain.env` file.
+
 ### `0.5.x-beta` -> `0.6.x-beta`
 
 - Using `{{ .Domain }}` in recipe `.envrc.sample` files went away because it

docs/maintainers/handbook.md

@@ -8,6 +8,15 @@ You can run `abra recipe new <recipe>` to generate a new `~/.abra/recipes/<recip
 
 ## Hacking on an existing recipe
 
+!!! warning
+
+    It is *very advisable* to disable any `healthcheck: ...` configuration
+    while hacking on new recipes. This is because it is very easy to mess up
+    and it will stop Traefik or other web proxies routing the app. You can
+    enable a specific healthcheck later when your recipe is stable. The default
+    "unconfigured" healthcheck behaviour is much less strict and it's faster to
+    get something up and running.
+
 If you want to make changes to an existing recipe then you can simply edit the files in `~/.abra/recipes/<recipe-name>` and run pass `--chaos` to the `deploy` command when deploying those changes. `abra` will not deploy unstaged changes to avoid instability but you can tell it to do so with `--chaos`. This means ou can simple hack away on the existing recipe files on your local file system and then when something is working, submit a change request to the recipe upstream.
 
 ## How is a recipe structured?
@@ -30,7 +39,7 @@ After docker creates the filesystem and copies files into a new container it run
 
 For a simple example check the [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. See [this handbook entry](http://localhost:8000/maintainers/handbook/#entrypoints) for more.
+If you write your own entrypoint, it needs to be specified in the `config` section of compose.yml. See [this handbook entry](/maintainers/handbook/#how-do-i-set-a-custom-entrypoint) for more.
 
 ### `releases/` directory
 
@@ -539,3 +548,91 @@ You can use [this `docker-compose` trick](https://docs.docker.com/compose/extend
 If you have a recipe that is using a `mysql` service and you'd like to use `postgresql` instead, you can create a `compose.psql.yml`!
 
 An example of this is the [`selfoss`](https://git.coopcloud.tech/coop-cloud/selfoss) recipe. The default is `sqlite` but there is a `postgresql` compose configuration there too.
+
+## How do I set a custom entrypoint?
+
+For more context, see the [`entrypoint.sh`](/maintainers/handbook/#entrypointsh) section. The following configuration example is ripped from the [`coop-cloud/peertube`](https://git.coopcloud.tech/coop-cloud/peertube) recipe but shortened down. Here are more or less the steps you need to take:
+
+Define a config:
+
+```yaml
+  app:
+    ...
+    configs:
+      - source: app_entrypoint
+        target: /docker-entrypoint.sh
+        mode: 0555
+    ...
+
+configs:
+  app_entrypoint:
+    name: ${STACK_NAME}_app_entrypoint_${APP_ENTRYPOINT_VERSION}
+    file: entrypoint.sh.tmpl
+    template_driver: golang
+```
+
+Define a `entrypoint.sh.tmpl`:
+
+```
+#!/bin/bash
+
+set -e
+
+file_env() {
+   local var="$1"
+   local fileVar="${var}_FILE"
+   local def="${2:-}"
+
+   if [ "${!var:-}" ] && [ "${!fileVar:-}" ]; then
+      echo >&2 "error: both $var and $fileVar are set (but are exclusive)"
+      exit 1
+   fi
+
+   local val="$def"
+
+   if [ "${!var:-}" ]; then
+      val="${!var}"
+   elif [ "${!fileVar:-}" ]; then
+      val="$(< "${!fileVar}")"
+   fi
+
+   export "$var"="$val"
+   unset "$fileVar"
+}
+
+file_env "PEERTUBE_DB_PASSWORD"
+
+{{ if eq (env "PEERTUBE_SMTP_ENABLED") "1" }}
+file_env "PEERTUBE_SMTP_PASSWORD"
+{{ end }}
+
+{{ if eq (env "PEERTUBE_LIVE_CHAT_ENABLED") "1" }}
+apt -y update && apt install -y prosody && apt -y clean
+mkdir -p /run/prosody && chown prosody:prosody /run/prosody
+{{ end }}
+
+# Copy the client files over to a named volume
+# so that they may be served by nginx directly
+cp -ar /app/client/dist /srv/client
+
+# upstream entrypoint
+# https://github.com/Chocobozzz/PeerTube/blob/66f77f63437c6774acbd72584a9839a7636ea167/support/docker/production/entrypoint.sh
+/usr/local/bin/entrypoint.sh "$@"
+```
+
+Please note:
+
+1. The `file_env` // `_FILE` hack is to pass secrets into the container runtime without exposing them in plaintext in the configuration. See [this entry](/maintainers/handbook/#exposing-secrets) for more.
+
+1. In order to pass execution back to the original entrypoint, it's a good idea to find the original entrypoint script and run it from your own entrypoint script. If there is none, you may want to reference the `CMD` definition or if that isn't working, try to actually specify `cmd: ...` in the `compose.yml` definition (there are other recipes which do this).
+
+1. If you're feeling reckless, you can also use the Golang templating engine to do things conditionally.
+
+Then, wire up the vendored config version:
+
+```
+# abra.sh
+export APP_ENTRYPOINT_VERSION=v5
+```
+
+You should be able to deploy this overriden configuration now.

docs/operators/handbook.md

@@ -368,3 +368,20 @@ If you get errors about database access:
 ```
 abra app run foo.bar.com db bash -c 'mysqldump -u root -p"$(cat /run/secrets/db_oot_password)" <database>' | gzip > ~/.abra/backups/foo.bar.com_db_`date +%F`.sql.gz
 ```
+
+## Can I deploy a recipe without `abra`?
+
+Yes! It's a design goal to keep the recipes not dependent on `abra` or any
+single tool that we develop. This means the configurationc commons can still be
+useful beyond this project. You can deploy a recipe with standard commands like
+so:
+
+```
+set -a
+source example.com.env
+cd ~/.abra/recipes/myrecipe
+docker stack deploy -c compose.yml example_com
+```
+
+`abra` makes all of this more cenvenient but other tooling could follow this
+approach.

requirements.txt

@@ -1,4 +1,4 @@
 mkdocs-awesome-pages-plugin==2.8.0
 mkdocs-material-extensions==1.1.1
-mkdocs-material==9.0.11
+mkdocs-material==9.0.12
 mkdocs==1.4.2