add FAQ: Running an offline coop-cloud server

Closes coop-cloud/organising#291.

Dockerfile

@@ -1,4 +1,4 @@
-FROM squidfunk/mkdocs-material:8.2.1
+FROM squidfunk/mkdocs-material:8.2.5
 
 EXPOSE 8000
 

docs/abra/trouble.md

@@ -67,3 +67,7 @@ docker context create <domain> --docker "host=ssh://<user>@<domain>:<port>"
 ## Command-line flag handling is weird?
 
 Unfortunately, there is a limitation in our underlying command-line library implementation for `abra` ([ref](https://github.com/urfave/cli/issues/1113)) (and more fundamentally in the design of flags in the Go programming language itself ([ref](https://utcc.utoronto.ca/~cks/space/blog/programming/GoFlagUIImportance))). We're aiming to work with upstream to resolve the flag handling but this it is not yet clear when this will be resolved.
+
+## Why can't `abra` support multiline definitions in the `.env` files?
+
+We're sorry, it's an issue with an upstream dependency. See [`#291`](https://git.coopcloud.tech/coop-cloud/organising/issues/291) for more.

docs/maintainers/handbook.md

@@ -443,3 +443,22 @@ If you want to get the highest rating on SSL certs, you can use the following tr
 ```
 
 See [this PR](https://git.coopcloud.tech/coop-cloud/traefik/pulls/8/files) for the technical details
+
+## Tweaking secret generation length
+
+It is possible to tell `abra` which length it should generate secrets with from your recipe config.
+
+You do this by adding a inline comment to the secret definition in the `.env.sample` / `.env` file.
+
+Here are examples from the gitea recipe:
+
+```
+SECRET_INTERNAL_TOKEN_VERSION=v1 # length=105
+SECRET_JWT_SECRET_VERSION=v1 # length=43
+SECRET_SECRET_KEY_VERSION=v1 # length=64
+```
+
+When using this length specifier, `abra` will not use the "easy to remember
+word" style generator but instead a string of characters to match the exact
+length. This can be useful if you have to generate "key" style values instead
+of passwords which admins have to type out in database shells.

docs/operators/handbook.md

@@ -86,7 +86,7 @@ Then, tell your collaborators (e.g. in the repository's `README.md`), to run `ma
 
 If you're on an environment where it's hard to run Docker, or command-line programs in general, you might want to install `abra` on a server instead of your local work station.
 
-To install `abra` on a different server than you'll be hosting your apps, just follow [getting started guide](/operators/tutorial#deploy-your-first-app) as normal except for one difference. Instead of providing your SSH connection details when you run `abra server add ...`, just pass `--local`.
+To install `abra` the same server where you'll be hosting your apps, just follow [getting started guide](/operators/tutorial#deploy-your-first-app) as normal except for one difference. Instead of providing your SSH connection details when you run `abra server add ...`, just pass `--local`.
 
 ```
 abra server add --local
@@ -228,3 +228,23 @@ If you want to teach `abra` how to support your favourite server hosting provide
 `abra` supports creating, listing and removing DNS entries if the 3rd party integration supports it.
 
 If you want to teach `abra` how to support your favourite server hosting provider, we'd glady accept patches.
+
+## Running an offline coop-cloud server 
+
+You may want to run a coop-cloud directly on your device (or in a VM or machine on your LAN), whether that's for testing a recipe or to run coop-cloud apps outside of the cloud ;-)
+In that case you might simply add some names to `/etc/hosts` (e.g `127.0.0.1 myapp.localhost`), or configure them on a local DNS server - which means `traefik` won't be able to use `letsencrypt` to generate and verify SSL certificates. Here's what you can do instead:
+1. In your traefik .env file, edit/uncomment the following lines:
+```
+LETS_ENCRYPT_ENV=staging
+WILDCARDS_ENABLED=1
+SECRET_WILDCARD_CERT_VERSION=v1
+SECRET_WILDCARD_KEY_VERSION=v1
+COMPOSE_FILE="$COMPOSE_FILE:compose.wildcard.yml"
+```
+2. Generate a self-signed certificate using the [command listed here](https://letsencrypt.org/docs/certificates-for-localhost/#making-and-trusting-your-own-certificates). Unless using `localhost` you may want to edit that where it appears in the command, and/or add multiple (sub)domains to the certificate e.g: `subjectAltName=DNS:localhost,DNS:myapp.localhost`
+3. Run these commands:
+```
+abra app secret insert localhost ssl_cert v1 "$(cat localhost.crt)"
+abra app secret insert localhost ssl_key v1 "$(cat localhost.key)"
+```
+4. Re-deploy `traefik` with `--force` and voila!

requirements.txt

@@ -1,4 +1,4 @@
 mkdocs-awesome-pages-plugin==2.7.0
 mkdocs-material-extensions==1.0.3
-mkdocs-material==8.2.1
+mkdocs-material==8.2.5
 mkdocs==1.2.3