Add basic Decap CMS files

See coop-cloud/abra#391.

Dockerfile

@@ -1,4 +1,4 @@
-FROM squidfunk/mkdocs-material:9.4.10
+FROM squidfunk/mkdocs-material:9.5.7
 
 EXPOSE 8000
 
@@ -9,5 +9,6 @@ WORKDIR /docs
 RUN apk add --no-cache curl
 
 RUN pip install \
-  mkdocs-awesome-pages-plugin==2.9.1 \
+  mkdocs-material~=9.5.7 \
-  mkdocs-material-extensions==1.1.1
+  mkdocs-material-extensions~=1.3.1 \
+  mkdocs-awesome-pages-plugin==2.9.2

README.md

@@ -1,13 +1,21 @@
-# docs.coopcloud.tech
+# docs.coopcloud.tech :open_book:
 
 [![Build Status](https://build.coopcloud.tech/api/badges/coop-cloud/docs.coopcloud.tech/status.svg)](https://build.coopcloud.tech/coop-cloud/docs.coopcloud.tech)
 
-> https://docs.coopcloud.tech
+View: [docs.coopcloud.tech](https://docs.coopcloud.tech)
 
-## hacking
+
+## Developing / Hacking
+
+Co-op Cloud's docs are created with the [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) framework.
+
+To install dependencies and serve local build of site, simply run:
 
 ```
 make
 ```
 
-Theme docs are [here](https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/) and [there](https://squidfunk.github.io/mkdocs-material/reference/).
+Useful docs for theming and content reference:
+
+- [Changing the colors](https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/)
+- [Reference](https://squidfunk.github.io/mkdocs-material/reference/)

docs/abra/hack.md

@@ -10,10 +10,11 @@ Install [direnv](https://direnv.net), run `cp .envrc.sample .envrc`, then run `d
 
 Install [Go >= 1.16](https://golang.org/doc/install) and then:
 
-- `make build` to build
+- `make build` to build. If this fails, run `go mod tidy`.
 - `./abra` to run commands
 - `make test` will run tests
-- `make install` will install it to `$GOPATH/bin`
+- `make install-abra` will install abra to `$GOPATH/bin`
+- `make install-kadabra` will install kadabra to `$GOPATH/bin`
 - `go get <package>` and `go mod tidy` to add a new dependency
 
 Our [Drone CI configuration](https://git.coopcloud.tech/coop-cloud/abra/src/branch/main/.drone.yml) runs a number of checks on each pushed commit. See the [Makefile](https://git.coopcloud.tech/coop-cloud/abra/src/branch/main/Makefile) for more handy targets.
@@ -61,14 +62,16 @@ cd bats-core
 sudo ./install.sh /usr/local
 ```
 
-### Run tests
+### Setup Test Server
 
-Then you can run the integration test suite with the following.
+For many tests an actual server is needed, where apps can be deployed. You can
+either use a local one or a remote test server.
+
+#### With remote test server
 
 ```
 export ABRA_TEST_DOMAIN="test.example.com"
 export ABRA_DIR="$HOME/.abra_test"
-bats -Tp tests/integration # DO NOT run this just yet, read below...
 ```
 
 `ABRA_TEST_DOMAIN` should also have a DNS A record for `*.test.example.com`
@@ -80,6 +83,32 @@ Traefik for you. Then you'll have more stable results.
 You probably don't want to run the entire test suite though, it takes a while.
 Try the following for starters.
 
+#### With local swarm
+
+When running the test suite localy you need a running docker swarm setup:
+
+```
+docker swarm init
+docker network create -d overlay proxy
+```
+
+To use the local swarm set the foloowing env var:
+
+```
+export TEST_SERVER=default
+export ABRA_DIR="$HOME/.abra_test"
+```
+
+### Run tests
+
+Now you can run the whole test suite:
+
+```
+bats -Tp tests/integration
+```
+
+Or you can run a single test file:
+
 ```
 bats -Tp tests/integration/autocomplete.bats
 ```
@@ -224,7 +253,7 @@ For developers, while using this `-beta` format, the `y` part is the "major" ver
 
 ### `godotenv`
 
-We maintain a fork of [godotenv](https://github.com/Autonomic-Cooperative/godotenv) because we need inline comment parsing for environment files. You can upgrade the version here by running `go get github.com/Autonomic-Cooperative/godotenv@<commit>` where `<commit>` is the latest commit you want to pin to. At time of writing, `go get github.com/Autonomic-Cooperative/godotenv@b031ea1211e7fd297af4c7747ffb562ebe00cd33` is the command you want to run to maintain the above functionality.
+We maintain a fork of [godotenv](https://git.coopcloud.tech/coop-cloud/godotenv) because we need inline comment parsing for environment files. You can upgrade the version here by running `go get git.coopcloud.tech/coop-cloud/godotenv@0<COMMID>` where `<commit>` is the latest commit you want to pin to. See [`abra#391`](https://git.coopcloud.tech/coop-cloud/abra/pulls/391) for more.
 
 ### `docker/client`
 

docs/abra/install.md

@@ -4,7 +4,7 @@ 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.
+    02/2023: 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. However, this might be fixed with newer versions of Docker.
 
 ## Stable release
 
@@ -18,6 +18,10 @@ curl https://install.abra.coopcloud.tech | bash
 curl https://install.abra.coopcloud.tech | bash -s -- --rc
 ```
 
+## Compile from source
+
+Follow the guide [here](https://docs.coopcloud.tech/abra/hack/)
+
 ## Installer script source
 
 You can view that [here](https://git.coopcloud.tech/coop-cloud/abra/src/branch/main/scripts/installer/installer).

docs/abra/trouble.md

@@ -20,6 +20,12 @@ Host example.com
   IdentityFile ~/.ssh/example@somewhere
 ```
 
+and your IdentityFile should be added to the authentication agent:
+
+```
+ssh-add ~/.ssh/example@somewhere
+```
+
 ## "abra server ls" shows the wrong details?
 
 You can use `abra server rm` to remove the incorrect details. Make sure to take a backup of your `~/.abra/servers/<domain>` first. You can then try to re-create by using `abra server add ...` again.

docs/admin/config.yml

@@ -0,0 +1,26 @@
+display_url: "https://docs.coopcloud.tech/"
+logo_url: "/img/coop_cloud_logo_pink.png"
+backend:
+  name: gitea
+  repo: coop-cloud/docs.coopcloud.tech
+  branch: main
+  app_id: c5bb5fe3-d24d-4246-b790-7455a271d1e8
+  site_domain: docs.coopcloud.tech
+  api_root: https://git.coopcloud.tech/api/v1
+  base_url: https://git.coopcloud.tech
+  auth_endpoint: https://git.coopcloud.tech/login/oauth/authorize
+media_folder: img
+public_folder: /img
+collections:
+  - name: 'docs'
+    label: 'Docs'
+    create: true
+    folder: 'docs/'
+    slug: '{{slug}}'
+    fields: 
+      - label: 'Title'
+        name: 'title'
+        widget: 'string'
+      - label: "Body"
+        name: "body"
+        widget: "markdown"

docs/admin/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html>
+    <head>
+        <meta charset="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <meta name="robots" content="noindex" />
+        <title>Co-op Cloud: Docs Editor</title>
+    </head>
+    <body>
+        <script src="https://unpkg.com/decap-cms@latest/dist/decap-cms.js"></script>
+    </body>
+</html>

docs/federation/membership.md

@@ -15,3 +15,4 @@ title: Membership
 | ruangrupa | - | - | Henry `@babystepper:matrix.org` |
 | UTAW | - | - | `@javielico:matrix.org` |
 | ??? | - | - | `@mirsal:1312.media` |
+| Klasse & Methode | - | - | `@p4u1_f4u1:matrix.org` |

docs/federation/resolutions/drafts/013.md

@@ -0,0 +1,73 @@
+---
+title: "Resolution 013: Budget 007: Operator sync - 2024-01-??"
+---
+
+!!! note
+
+      This resolution has been amended! The main change was to remove automatic
+      git synchronisation; please see [the file
+      history](https://git.coopcloud.tech/coop-cloud/docs.coopcloud.tech/commits/branch/main/docs/federation/resolutions/in-progress/013.md) for a full run-down.
+
+- Deadline: 2024-01-XX
+- Size: Large
+
+### Summary
+
+As highlighted in several tickets (e.g. [`#434`](https://git.coopcloud.tech/coop-cloud/organising/issues/434), [`#467`](https://git.coopcloud.tech/coop-cloud/organising/issues/467)), several operators working together on the same server routinely run into deployment instability. This is due to the fact that we do not store the deployment version of the apps.
+
+With this proposal, we would like to address the synchronisation of app deployment versions. This is being called "Operator sync". What follows is the design proposal which has already received feedback from operators on [this pad](https://pad.riseup.net/p/IebZQkpe3OOpYyVT8f1j-keep).
+
+### Details (Budget 007)
+
+We add support a config file (`$ABRA_DIR/config.yml`) which has these defaults:
+
+We also add a `abra config` command which has the following shape:
+
+```
+🌻 ./abra config -h
+NAME:
+   abra config - Manage system-wide Abra configuration
+
+USAGE:
+   abra config command [command options]
+
+COMMANDS:
+   generate, g  Generate default configuration
+
+OPTIONS:
+   --help, -h  show help
+```
+
+If there is no `$ABRA_DIR/config.yml` or `sync: false`, nothing changes. When `sync: true`, *only* the `abra app deploy / upgrade / rollback` commands have new behaviour.
+
+There is also a new command `abra app sync <domain>` which triggers a synchronisation.
+
+When `abra app deploy/upgrade/rollback/sync` is run, here's what we do:
+
+* Read the `OPERATOR_SYNC_VERSION` env var as the version to deploy / upgrade from / rollback from
+    * upgrade: if deployed version does not match `OPERATOR_SYNC_VERSION`, warn before overview
+    * rollback: same as above!
+
+* Run the deployment
+    * if successful, record a new `OPERATOR_SYNC_VERSION`
+    * if unsuccessful, do not record a `OPERATOR_SYNC_VERSION` and ask operator to resolve
+
+If `--chaos` is passed, we use the short commit hash instead of the version label.
+
+Here's an example of the `OPERATOR_SYNC_VERSION` env var:
+
+```
+# in ~/.abra/servers/example.com/matrix.example.com.env
+TYPE=matrix-synapse
+OPERATOR_SYNC_VERSION=4.0.0+v1.93.0 # managed by Abra
+```
+
+Operator documentation will also be provided.
+
+**Budget amount**: 200 EUR (10 hrs * 20 EUR/hr)
+
+**Who will implement this**: (someone?)
+
+**When will the money be spent**: Before mid-February 2024
+
+**What is the money for**: Implementing the first steps of operator sync.

docs/federation/resolutions/in-progress/016.md

@@ -0,0 +1,46 @@
+---
+title: "Resolution 016: Budget 008: Backup-bot-two Documentation and Specification - 27-01-2024"
+---
+
+- Deadline: 10th February 2024
+- Size: Large
+
+### Summary
+
+> (Co-written by p4u1 & d1)
+
+The new backup-bot-two implementation is nearly finished. The only remaining step is to implement restore functionality. In a recently meeting with Moritz, p4u1 & d1, we discussed how to design and implement it. The mintues are [here](https://pad.riseup.net/p/UEC2JUPGb6tmRCZ7RX9X-keep).
+
+In this meeting, we realised that there is already a lot of implicit, undocumented knowledge about how backup-bot-two & abra work together. How the restore interface will work is more or less designed in the meeting, with general agreement.
+
+In order to communicate that design, we feel we need to have clear documentation and a specification on how things work. This will make sure we have consensus before commiting more budget to implementing the final step. It will also help operators pick up, use & extend backup-bot-two in the future.
+
+In this resolution, we want to propose to write the initial documentation and specification for the new [backup-bot-two](https://git.coopcloud.tech/coop-cloud/backup-bot-two/).
+
+The existing documentation for the old backupbot should be taken into account wherever possible.
+
+### Details (Budget 008)
+
+Documentation should be for:
+
+- Operators using the backup-bot-two
+- Maintainers of recipes
+
+The documentation should have:
+
+- Examples on using Abra with the backupbot
+- Examples of recipe configurations
+- Detailed explanation of features and their limitations
+
+The Specification should include:
+
+- Detailed specification on how annotations work
+- With the specification it should be possible to implement backup and restore
+  without looking at the backupbot-two code
+
+---
+
+- Budget amount: 200 EUR (10 hrs * 20 EUR/hr)
+- Who will implement this: p4u1
+- When will the money be spent: Before the end of February
+- What is the money for: Writing documentation and specification for backup-bot-two

docs/federation/resolutions/in-progress/017.md

@@ -0,0 +1,19 @@
+---
+title: "Resolution 17: BeWater joins the Co-op Cloud Federation - 30-01-2024"
+---
+
+- Deadline: 13-02-2024
+- Size: Large
+
+### Summary
+
+[BeWater Co-op](https://bewater.contact).
+
+`@decentral1se` is a member and has been active in Abra hacking & coordination
+on several issues. BeWater maintains several small-scale Co-op Cloud
+deployments.
+
+### Details
+
+BeWater is just starting and we're currently unable to pay the membership fees
+at this time and ask for a waiver for 1 year. To be revisited on 30-01-2025.

docs/federation/resolutions/passed/014.md

@@ -0,0 +1,43 @@
+---
+title: "Resolution 014: Budget 008: Critical Fixes - 2023-12-06"
+---
+
+- Deadline: 2023-12-24
+- Size: Large
+
+## Summary
+
+We (decentral1se, wykwit, moritz, knoflook) have identified bugs and lacking features that are a big obstacle to using abra.
+
+We have roughly estimated the work to fix the bugs to take between 27 and 75 hours. We would also like to request onboarding budget for two new developers to smoothly get started on the bug fixes (10 hours per person).
+
+We'd like to request no more than 1900€ of budget to cover the labor and onboarding. If less than 95 hours is spent, the remaining budget will not be paid out.
+
+## Details
+
+estimating: small (1-3 hours), medium (3-8 hours), large (8-15 hours) & order is priority.
+
+
+| NAME | estimation |
+| ---- | ----- |
+| [#535 Comment parsing and modifiers](https://git.coopcloud.tech/coop-cloud/organising/issues/535) | Large |
+| [#519 abra app new `[<recipe>]` `[<version>]`](https://git.coopcloud.tech/coop-cloud/organising/issues/519) | Medium |
+| [#518 Abra fails silently if required image doesn't exist](https://git.coopcloud.tech/coop-cloud/organising/issues/518) | Medium |
+| [#527 abra catalogue generate `<recipe name>` ignores the specified recipe](https://git.coopcloud.tech/coop-cloud/organising/issues/527) | Small |
+| [#509 abra app remove could wait until volume is not in use](https://git.coopcloud.tech/coop-cloud/organising/issues/509) | Medium |
+| [#530 abra recipe fetch can only fetch a single recipe](https://git.coopcloud.tech/coop-cloud/organising/issues/530) | Medium |
+| [#525 prevent abra app cp from applying file permissions.](https://git.coopcloud.tech/coop-cloud/organising/issues/525) | Medium |
+| [#537 Fix the operators tutorial](https://git.coopcloud.tech/coop-cloud/organising/issues/537) | Medium |
+
+Estimation: best case: (8 * 1) + (3 * 6) + (1 * 1) = 27 hours
+Estimation: worst case: (15 * 1) + (8 * 6) + (1 * 3) = 73 hours
++ 10 hours for onboarding * 2 people = 47-93 hours
+
+
+**Budget amount**: 1900€/95 hours at maximum
+
+**Who will implement this:** p4u1, wykwit, moritz, knoflook
+
+**When will the money be spent:** Before the end of February 2024.
+
+**What is the money for:** Fixing bugs and improving operator docs.

docs/federation/resolutions/passed/015.md

@@ -0,0 +1,19 @@
+---
+title: "Resolution 15: Klasse & Methode joins the Co-op Cloud Federation - 25-01-2024"
+---
+
+- Deadline: 08-02-2024
+- Size: Large
+
+### Summary
+
+[Klasse & Methode - IT Kollektiv Stuttgart](https://codeberg.org/Klasse-Methode).
+
+`@p4u1` has been active in Abra hacking & coordination on several issues. K & M
+manage a Co-op Cloud deployment with 9 apps running at the time of the
+proposal.
+
+### Details
+
+K & M is volunteer based and are unable to pay the membership fees at this time
+and ask for a waiver for 1 year. To be revisited on 25-01-2025.

docs/maintainers/handbook.md

@@ -396,6 +396,8 @@ mkdir -p releases
 
 And then create a text file which corresponds to the version release, e.g. `1.1.0+5.9.0` and write some notes. `abra` will show these when another operator runs `abra app deploy` / `abra app upgrade`.
 
+You can also add release notes for the next release into a special file `releases/next`. This file will be used when running `abra recipe release`.
+
 ## How do I generate the recipe catalogue
 
 To generate an entire new copy of the catalogue:

docs/maintainers/index.md

@@ -1,8 +1,23 @@
 ---
-title: Maintainers guide
+title: Maintainers Guide
 ---
 
 Welcome to the maintainers guide! Maintainers are typically individuals who have a stake in building up and maintaining our digital configuration commons, the recipe configurations. Maintainers help keep recipes configurations up to date, respond to issues in a timely manner, help new users within the community and recruit new maintainers when possible.
 
-- [New maintainers tutorial](/maintainers/tutorial): If you want to package a recipe and/or become a maintainer, start here :rocket:
+<div class="grid cards" markdown>
-- [Packaging handbook](/maintainers/handbook): One-stop shop for all you need to know to package recipes :package:
+
+- __New maintainers tutorial__
+
+    If you want to package a recipe and/or become a maintainer, start here :rocket:
+
+    [Get Started](/maintainers/tutorial){ .md-button .md-button--primary }
+
+- __Packaging handbook__
+
+    One-stop shop for all you need to know to package recipes :package:
+
+    [Read Handbook](/maintainers/handbook){ .md-button .md-button--primary }
+
+</div>
+
+Maintainers are encouraged to submit documentation patches! Sharing is caring :sparkling_heart:

docs/operators/handbook.md

@@ -1,5 +1,5 @@
 ---
-title: Operations handbook
+title: Operators Handbook
 ---
 
 ## Understanding `~/.abra`

docs/operators/index.md

@@ -2,7 +2,22 @@
 title: Operators Guide
 ---
 
-Welcome to the operators guide! Operators are typically individuals, members of tech co-ops or collectives who provide services powered by Co-op Cloud. This documentation is meant to help new & experienced operators manage their deployments as well as provide a space for sharing tricks & tips for keeping things running smoothly. Operators are encouraged to submit documentation patches! Sharing is caring :sparkling_heart:
+Welcome to the operators guide! Operators are typically individuals, members of tech co-ops or collectives who provide services powered by Co-op Cloud. This documentation is meant to help new & experienced operators manage their deployments as well as provide a space for sharing tricks & tips for keeping things running smoothly.
 
-- [New operators tutorial](/operators/tutorial): If you want to become an operator, start here :rocket:
+<div class="grid cards" markdown>
-- [Operations handbook](/operators/handbook): One-stop shop for all you need to know to manage a deployment :ribbon:
+
+- __New Operators Tutorial__
+
+    If you want to become an operator, start your journey here :rocket:
+
+    [Get started](tutorial.md){ .md-button .md-button--primary }
+
+- __Operators Handbook__
+
+    One-stop shop for all you need to know to manage a deployment :ribbon:
+
+    [Read Handbook](handbook.md){ .md-button .md-button--primary }
+
+</div>
+
+Operators are encouraged to submit documentation patches! Sharing is caring :sparkling_heart:

docs/operators/tutorial.md

@@ -1,5 +1,5 @@
 ---
-title: New operators tutorial
+title: New Operators Tutorial
 ---
 
 ## The moving parts

docs/organisers/index.md

@@ -4,6 +4,20 @@ title: Organisers Guide
 
 Welcome to the organisers guide! Organisers are folks who focus on the social work in the project. Speaking for the project at talks, helping new tech co-ops & collectives join, keeping an eye out for funding opportunities, seeing what things come up in the community chats, etc. It's important work.
 
-We're still working out what it looks like to do this kind of work in the project. If you like the idea of this kinda of work and/or are already doing it, please send patches to improve this documentation :rocket:
+<div class="grid cards" markdown>
 
-- [Organising handbook](/organisers/handbook): One-stop shop for all you need to know to organise in the community :sparkles:
+- __Organisers handbook__
+
+    One-stop shop for all you need to know to organise in the community :sparkles:
+
+    [Read Handbook](/organisers/handbook){ .md-button .md-button--primary }
+
+- __Say Hello First__
+
+    If you like what you see, but are not sure how to best contribute :speech_left:
+
+    [Get In Touch](/get-involved/){ .md-button .md-button--primary }
+
+</div>
+
+We're still working out what it looks like to do this kind of work in the project. If you like the idea of this kinda of work and/or are already doing it, please send patches to improve this documentation :rocket:

docs/styles/extra.css

@@ -4,6 +4,14 @@
   --md-primary-fg-color--dark: #ee4a33;
 }
 
+/* Button styling tweaks */
+
+.md-button {
+  margin: .25em !important;
+  padding: .15em .6em !important;
+  font-size: .85em !important;
+}
+
 /* Navbar styling tweaks */
 
 .md-search__form {

mkdocs.yml

@@ -26,20 +26,28 @@ theme:
 copyright: Copyleft 2023 Co-op Cloud
 
 markdown_extensions:
-  - meta
   - admonition
+  - attr_list
   - codehilite:
       guess_lang: false
+  - def_list
+  - footnotes
+  - md_in_html
+  - meta
   - toc:
       permalink: true
-  - attr_list
+  - pymdownx.betterem:
-  - pymdownx.tabbed
+      smart_enable: all
-  - pymdownx.superfences
+  - pymdownx.details
-  - pymdownx.tilde
-  - pymdownx.magiclink
   - pymdownx.emoji:
-      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
-      emoji_generator: !!python/name:materialx.emoji.to_svg
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+  - pymdownx.magiclink
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.superfences
+  - pymdownx.tabbed
+  - pymdownx.tilde
 
 nav:
   - "Introduction":
@@ -101,10 +109,15 @@ nav:
           - federation/resolutions/passed/010.md
           - federation/resolutions/passed/011.md
           - federation/resolutions/passed/012.md
+          - federation/resolutions/passed/014.md
+          - federation/resolutions/passed/015.md
         - "In progress":
           - federation/resolutions/in-progress/index.md
+          - federation/resolutions/in-progress/016.md
+          - federation/resolutions/in-progress/017.md
         - "Draft":
           - federation/resolutions/drafts/index.md
+          - federation/resolutions/drafts/013.md
       - "Finance": federation/finance.md
       - "Membership": federation/membership.md
       - "Minutes":

requirements.txt

@@ -1,4 +1,15 @@
+markdown~=3.2
+
+mkdocs~=1.5.3
+mkdocs-material~=9.5.7
+mkdocs-material-extensions~=1.3.1
 mkdocs-awesome-pages-plugin==2.9.2
-mkdocs-material-extensions==1.3
+pygments~=2.16
-mkdocs-material==9.4.10
+pymdown-extensions~=10.2
-mkdocs==1.5.3
+
+# Requirements for plugins
+babel~=2.10
+colorama~=0.4
+paginate~=0.5
+regex>=2022.4
+requests~=2.26