can switch between languages now

Closes coop-cloud/organising#400

Dockerfile

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

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/index.pl.md

@@ -0,0 +1,33 @@
+---
+title: Wstęp
+---
+
+## Who is this for?
+
+Witaj w dokumentacji Co-op Cloud!
+
+Ta dokumentacja jest skierowana do odbiorców "technicznych": spółdzielni technologicznych, kolektywów i osób indywidualnych zainteresowanych Co-op Cloud, lub takich, które mają już deploymenty Co-op Cloud.
+
+A more general public may still find these pages useful but if you're just looking for a quick overview of the project from a less technical perspective, you can take a look at [coopcloud.tech](https://coopcloud.tech).
+
+We'd be happy to hear feedback about our documentation, if it was helpful, what was missing, what was confusing, etc., please [get in touch](/intro/contact)!
+
+## Quick start
+
+!!! danger "Here be dragons"
+
+    This project is still [beta quality software](https://en.wikipedia.org/wiki/Software_release_life_cycle#Beta) :bomb: Please take that into consideration if you are thinking about using this system in production. We're working hard to make Co-op Cloud stable. In the meantime, this is a good time to help us out with initial testing, feedback, ideas or [join in with development](/get-involved/).
+
+- [Operators guide](/operators/): You run a Co-op Cloud based deployment or want to do so :computer:
+
+- [Maintainers guide](/maintainers/): You maintain recipes and ensure things run smoothly for operators :tools:
+
+- [Organisers guide](/organisers): You run meetings, write guidelines & shape our democratic process :fist:
+
+- [Recipes](/recipes/): You want to know what recipes are packaged so you can deploy them as apps :nerd:
+
+- [Abra](/abra): You want to install the command-line client and hack the planet :unicorn:
+
+- [Get involved](/get-involved): You'd like to help out with the project, we've love to see you stick around :heart:
+
+- [Glossary](/glossary/): You'd like clarification about project terminology :book:

docs/operators/handbook.md

@@ -370,3 +370,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.

docs/operators/tutorial.md

@@ -252,6 +252,46 @@ abra app errors -w <nextcloud-domain> # error catcher
 
 Your new `traefik` instance will detect that a new app is coming up and generate SSL certificates for it. You can see what `traefik` is up to using the same commands above but replacing `<netcloud-domain>` with the `<traefik-domain>` you chose earlier (`abra app ls` will remind you what domains you chose :grinning:).
 
+### Upgrade Nextcloud
+
+To upgrade an app manually to the newest available version run:
+
+```bash
+abra app upgrade <nextcloud-domain>
+```
+
+### Automatic Upgrades
+
+`kadabra` the auto-updater is still under development, use it with care and don't use it in production environments.
+To setup the auto-updater copy the `kadabra` binary to the server and configure a cronjob for regular app upgrades.
+The following script will configure ssmtp for email notifications and setup a cronjob.
+This cronjob checks daily for new app versions, notifies if any kind of update is available and upgrades all apps to the latest patch/minor version.
+
+
+```bash
+apt install ssmtp
+
+cat > /etc/ssmtp/ssmtp.conf << EOF
+mailhub=$MAIL_SERVER:587
+hostname=$MAIL_DOMAIN
+AuthUser=$USER
+AuthPass=$PASSWORD
+FromLineOverride=yes
+UseSTARTTLS=yes
+EOF
+
+cat > /etc/cron.d/abra_updater << EOF
+MAILTO=admin@example.com
+MAILFROM=noreply@example.com
+
+0  6 * * *       root    ~/kadabra notify --major
+30 4 * * *       root    ~/kadabra upgrade --all
+EOF
+
+
+```
+
+
 ## Finishing up
 
 Hopefully you got something running! Well done! The [operators handbook](/operators/handbook) would probably be the next place to go check out if you're looking for more help. Especially on topics of ongoing maintenance.

mkdocs.yml

@@ -78,6 +78,20 @@ nav:
 plugins:
   - search
   - awesome-pages
+  - translations:
+      default_language: en
+      languages:
+        en: english
+        pl: polski
+
+extra:
+  alternate:
+    - name: English
+      link: /en/
+      lang: en
+    - name: Polish
+      link: /pl/
+      lang: pl
 
 repo_name: coop-cloud/docs.coopcloud.tech
 repo_url: https://git.coopcloud.tech/coop-cloud/docs.coopcloud.tech

requirements.txt

@@ -1,4 +1,5 @@
 mkdocs-awesome-pages-plugin==2.8.0
 mkdocs-material-extensions==1.1.1
-mkdocs-material==9.0.9
+mkdocs-material==9.0.12
 mkdocs==1.4.2
+mkdocs-translations>=0.1.1