merge upstream

docs/federation/bylaws.md

@@ -28,4 +28,4 @@ According to [Resolution 002](/federation/resolutions/passed/002):
 
 > To join the federation an existing member must create a large decision to approve of the new member (paid or solidarity).
 
-So, please [get in touch](/intro/contact) if you'd like to join!
+So, please [read up here](/federation/join/) about the application process.

docs/federation/index.md

@@ -26,11 +26,11 @@ This is the public facing page where we publish all things federation in the ope
 
     [Our Members](/federation/membership){ .md-button .md-button--primary }
 
-- __Minutes__
+- __Join the Federation__
 
-    All minutes from our meetings 📒
+    How to join the Federation 📒
 
-    [Past Meetings](/federation/minutes){ .md-button .md-button--primary }
+    [Join us](/federation/join){ .md-button .md-button--primary }
 
 - __Digital Tools__
 

docs/federation/join.md

@@ -0,0 +1,21 @@
+---
+title: Joining the Co-op Cloud Federation (CCF)
+---
+
+Organisations that are aligned with our values (e.g. [vision](/federation/proposals/federation/#vision), [strategy](/intro/strategy/), [code of co-operation](/federation/code-of-coop/) and [bylaws](/federation/bylaws/)) can apply to join CCF.
+
+Read more about [membership benefits](/federation/proposals/federation/#benefits) and [responsibilities](/federation/proposals/federation/#responsibilities).
+
+## How to join
+
+1. Learn about Co-op Cloud and the Federation if you haven’t already: [The Co-op Cloud Federation Proposal](/federation/proposals/federation/#overview)
+1. Consider joining one of our “Kite Flying” regular online gatherings to introduce yourself and your organisation. You can [get in touch](/intro/contact) and/or check our [fediverse account](https://social.coop/@coopcloud) for announcements on the time/date for the upcoming Kite Flying.
+1. If you know someone who is already a member, ask them if they will be willing to vouch for you joining the CCF. We will ask them to submit the proposal for your joining.
+1. Email us at `helo@coopcloud.tech`, providing the following information as the basis for a proposal:
+    * Name of organisation.
+    * Summary (2 sentence overview of your orgnisation and why you wish to be a member)
+    * Details (further details regarding your use of Co-op Cloud software, and existing or planned involvement in the organisation.
+    * Name of your sponsor, if any
+    * Representative name.
+    * Matrix contact / email address.
+1. The other members of CCF will vote on the proposal for your organisation to join; you should hear from us within 2 weeks. We will ask you for a Matrix contact to include on our published list of member organisations.

docs/federation/membership.md

@@ -2,7 +2,7 @@
 title: Membership
 ---
 
-> Are you also interested in joining the federation? Please see [Resolution 002](/federation/resolutions/passed/002/) for our process on how to join. If you have any questions, [drop us a line](/intro/contact/) with us for a chat
+> Are you also interested in joining the federation? Please check [our process](/federation/join/) on how to join. If you have any questions, [drop us a line](/intro/contact/) or come for a chat.
 
 | Name      | Dues Paid | Notes    | Contact |
 | --------- | --------- | -------- |-------- |
@@ -21,3 +21,4 @@ title: Membership
 | [RTM](https://resisttechmonopolies.online) | ✅ | - | `@ammaratef45:matrix.org` + `@linnealovespie:matrix.org`|
 | [MIR](https://mirnet.org/) | ✅ | - | `@sixsmith:matrix.org` |
 | [Red Abya Yala](https://abyayala.sutty.nl/) | - | - | `@fauno:sutty.nl` |
+| [Merri-bek tech](https://www.merri-bek.tech/) | - | - | `coop-cloud-delegate@merri-bek.tech`|

docs/federation/resolutions/index.md

@@ -2,23 +2,4 @@
 title: Resolutions
 ---
 
-### Resolution Template
-
-``` yaml
----
-title: Resolution <number>
----
-
-- Topic: <title>
-- Date: 13-12-2023
-- Deadline: Date
-- Size: large or medium
-
-## Summary
-
-Who this affects, and what it does...
-
-## Details
-
-A narrative with details...
-```
+On the left-hand sidebar, you can view all draft/in-progress/passed and stalled resolutions.

docs/federation/resolutions/passed/038.md

@@ -0,0 +1,29 @@
+---
+title: "Resolution 038: Merri-bek Tech joins Co-op Cloud Federation"
+---
+
+- Topic: Merri-bek Tech joins Coopcloud
+- Date: 2026-03-02
+- Deadline: 2026-03-16
+- Size: Large
+
+### Summary
+
+Merri-bek Tech is working towards neighbourhood-first, community controlled web services, building infrastructure using  the Co-op Cloud stack. Merri-bek Tech expects to pay membership dues.
+
+### Details
+
+Merri-bek Tech
+
+- currently depends on Traefik for neighbourhood-distributed nodes.
+- have developed and are maintaining Kiwix Co-op Cloud recipe for deploying Wikipedia across neighbourhood nodes
+- plans to use and contribute to maintenance, of additional components of Co-op Cloud stack as needed for subsequent phases of the project roadmap: neighbhourhood based email service, web hosting and decentralized social media.
+
+@jade:merri-bek.chat is an active member of the Co-op Cloud community.
+The group is based in Merri-bek, in the inner Northern suburbs of Naarm (Melbourne), Australia
+
+[Merri-bek Tech Inc.] is legally an incorporated association in Australia, which is a legal entity used for democratic clubs and societies. It is not intended to be a worker co-operative, it is a volunteer commons project, but it shares the mutuality goals of cooperatives. Full details are at [merri-bek.tech](https://merri-bek.tech).
+
+The project that Merri-bek Tech is running to promote Neighbourhood-First Software in Merri-bek and other regions, is detailed at [lores.tech](https://lores.tech).
+
+@ammaratef45 from RTM is honored to vouch

docs/maintainers/index.md

@@ -18,9 +18,9 @@ Welcome to the recipe maintainers guide! Recipe maintainers help build up and ma
 
     [Get Started](/maintainers/tutorial){ .md-button .md-button--primary }
 
-- __How to Upgrade a Recipe__
+- __Recipe config upgrade checklist__
 
-    If you want to upgrade a recipe, start here 🤸‍♀️
+    If you want to upgrade a recipe config, please make sure you take these steps into consideration 🤸‍♀️
 
     [Start upgrading](/maintainers/upgrade){ .md-button .md-button--primary }
 

docs/maintainers/tutorial.md

@@ -1,9 +1,7 @@
 ---
-title: New maintainers tutorial
+title: Package your First Recipe Tutorial
 ---
 
-## Package your first recipe
-
 ### Overview
 
 Packaging a recipe is basically knowing a bag of about 20 tricks. Once you learn them, there is nothing more to learn. It can seem daunting at first but it's simple and easy to do once you know the tricks.

docs/maintainers/upgrade.md

@@ -1,15 +1,82 @@
 ---
-title: How to Upgrade a Recipe
+title: Recipe config upgrade checklist
 ---
 
+!!! warning "The recipe config commons is people!"
+
+    This documentation is all about helping you make recipe configuration
+    changes that won't break other peoples upgrade deployments :heart: There
+    are some specific maintainer responsibilities which are not exactly
+    obvious. This page is all about making them simple and clear to understand.
+    We hope it's clear and if not, please send documentation patches and/or
+    [get in touch](/intro/contact)!
+
 ## Updating versions in the `abra.sh`
 
-`#TODO`
+If you update a config in a recipe, you also need to update the associated config version.
+
+For example, in the [Traefik](https://git.coopcloud.tech/coop-cloud/traefik)
+recipe, we have the following in
+[`compose.yml`](https://git.coopcloud.tech/coop-cloud/traefik/src/branch/master/compose.yml#L104-L108):
+
+```yaml
+configs:
+  traefik_yml:
+    name: ${STACK_NAME}_traefik_yml_${TRAEFIK_YML_VERSION}
+    file: traefik.yml.tmpl
+    template_driver: golang
+```
+And in the [`abra.sh`](https://git.coopcloud.tech/coop-cloud/traefik/src/commit/9a46c85735701780dc8f0717a4e6cab4969420fc/abra.sh#L1), we have:
+
+```bash
+export TRAEFIK_YML_VERSION=v29
+```
+
+If you update the `traefik.yml.tmpl` with new changes, you **must** increment
+`TRAEFIK_YML_VERSION`. Otherwise, other Co-op Cloud operators will see an
+obscure error message when they try to deploy your new version.
 
 ## Backwards compatible environment variable changes
 
-`#TODO`
+If you add a new environment variable to the `.env.sample` then you can
+potentially create manual upgrade work for other Co-op Cloud operators.
+
+Depending on the functionality that the environment variable enables or how the
+recipe is already configured, it is possible to provide a default which
+maintains backwards compatibility. There is no hard and fast rule for this and it
+depends on the recipe and context.
+
+A typical way to do this, is to provide a default in the `environment` stanza.
+For example, providing a default of `false` for a new fictitous environment
+variable called `NEW_ENV_VAR` so other Co-op Cloud operators do not need to set
+`NEW_ENV_VAR=false` in their app `.env` file (unless they want to change it).
+
+```yaml
+environment:
+    - NEW_ENV_VAR=${NEW_ENV_VAR:-false}
+```
+
+Sometimes it is not appropriate to provide a default and it is important that
+other Co-op Cloud operators make an informed choice about the setting of an
+environment variable. In this case, please consider leaving a note about your
+new environment variables in the release notes (see below). The release of this
+change should then be considered a breaking change and require a major release
+version.
+
+`abra` will also warn Co-op Cloud operators about missing environment variables
+that are present in the recipe `.env.sample` but not in their app `.env` file.
 
 ## Creating new release notes
 
-`#TODO`
+Help other Co-op Cloud operators understand what they need to take care of when
+doing an upgrade deployment by creating some [release
+notes](/maintainers/handbook/#how-do-i-write-version-release-notes) about your
+specific changes.
+
+This is crucial when there are breaking changes, data migrations, work-arounds,
+hacks etc. present in the new changes. `abra` will show what you write when
+others run `abra app upgrade`.
+
+Good release notes are proven to save hours of pain and misery, so put
+solidarity into practice and write some excellent release notes for your fellow
+Co-op Cloud operators!

docs/operators/handbook.md

@@ -96,6 +96,8 @@ make link
 
 ## Configure `abra` with `abra.yml`
 
+You can place an `abra.yml`-file in the root of your .abra-project.
+
 There are few configuration options supported at this time but more can be added. We are open to requests!
 
 ### `$ABRA_DIR`
@@ -106,7 +108,7 @@ The lookup logic is defined like so.
 * look for config file and take value from there
 * $HOME/.abra as fallback
 
-If you create an `abra.yml` file in your `$PWD` with the following contents.
+If you create an `abra.yml` file in your `$PWD` (print working directory) with the following contents.
 
 ```
 abraDir: .
@@ -114,6 +116,12 @@ abraDir: .
 
 Then `$ABRA_DIR` will be automatically picked up as `$PWD`. This is useful when you maintain multiple project configurations and recipes in various state of chaos and would like to separate those. `abra` will create all the usual `$HOME/.abra` state (`servers`/`recipes`/etc.) under your chosen `abraDir` value. This allows you to have multiple independent versions of specific recipes which are relevant for specific projects vs. relying on a single `$ABRA_DIR/recipes/<recipe>` and constantly having to switch between different chaotic hacks.
 
+### `$EDITOR`
+
+When you edit .env.sample-files, you are asked to chose an editor. To avoid answering that question all the time, you can either set an environment variable (`export EDITOR=nano`), or you can set it as a config-option in abra.yml, like this:
+
+`editor: nano`
+
 ## Running abra server side
 
 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 computer.
@@ -219,6 +227,37 @@ By convention, the main `app` service is wired up to the "global" traefik overla
 
 To deal with this, we make an additional "internal" network for each app which is namespaced to that app. So, if you deploy a Wordpress instance called `my_wordpress_blog` then there will be a network called `my_wordpress_blog_internal` created. This allows all the services in an app to speak to each other but not be reachable on the public internet.
 
+### IPv6 Client IP Detection in Docker Swarm
+
+With Traefik using host-mode networking, you may notice that preserving the real Client IP works fine for IPv4, but fails for IPv6. Instead of the actual remote IPv6 address, the application receives a local IPv4 address (typically from the `172.18.0.x` range).
+When a Docker Swarm is initialized, it automatically creates a default bridge network called `docker_gwbridge` to handle external communications for swarm containers. By default, this network does not have IPv6 enabled. 
+When an IPv6 connection arrives at a host-published port, Docker must translate this into an IPv4 connection to reach Traefik on the IPv4 only network. This effectively masks the original client's IPv6 address behind the gateway's internal IPv4 address on the `docker_gwbridge` network.
+
+**Enable IPv6 on `docker_gwbridge`**
+To preserve the real IPv6 Client IP, the `docker_gwbridge` network must be created with IPv6 enabled **before** initializing Swarm. This allows traffic to be routed correctly without loosing the original client's IPv6 address.
+```bash
+# 1. Enable IPv6 in the Docker daemon
+# Add "ipv6": true to /etc/docker/daemon.json
+mkdir -p /etc/docker
+if [ -s /etc/docker/daemon.json ]; then
+  contents="$(jq '.ipv6 = true' /etc/docker/daemon.json)" && echo -E "${contents}" > /etc/docker/daemon.json
+else
+  echo '{
+    "ipv6": true
+}' > /etc/docker/daemon.json
+fi
+# 2. Restart the Docker service to apply the daemon configuration
+systemctl restart docker
+# 3. Create the IPv6-enabled docker_gwbridge
+docker network create --ipv6 \
+  --opt com.docker.network.bridge.name=docker_gwbridge \
+  --opt com.docker.network.bridge.enable_ip_forwarding=true \
+  --opt com.docker.network.bridge.enable_ip_masquerade=true \
+  docker_gwbridge
+# 4. Initialize the swarm (it will adopt the existing docker_gwbridge)
+docker swarm init
+```
+
 ## Multiple apps on the same domain?
 
 At time of writing (Jan 2022), we think there is a limitation in our design which doesn't support multiple apps sharing the same domain (e.g. `example.com/app1/` & `example.com/app2/`). `abra` treats each domain as unique and as the single reference for a single app.

docs/operators/tutorial.md

@@ -27,7 +27,7 @@ Assuming you've got a running server, it's now time to configure it.
 
 Co-op Cloud has very few system requirements. You only need to worry about the system resource usage of your apps and the overhead of running containers with the docker runtime (often negligible. If you want to know more, see [this FAQ entry](/intro/faq/#isnt-running-everything-in-containers-inefficient)).
 
-To get started, you'll need to install Docker, add your user to the Docker group & setup swarm mode. Many hosting providers support [cloud-init](https://cloudinit.readthedocs.io/en/latest/index.html), which allows you to automate the steps in this section. If that applies to you, you can use [our cloud-init file](https://git.coopcloud.tech/toolshed/abra/raw/branch/main/scripts/cloud-init/cloud-init.yaml).
+To get started, you'll need to install Docker, add your user to the Docker group & setup swarm mode. Many hosting providers support [cloud-init](https://cloudinit.readthedocs.io/en/latest/index.html), which allows you to automate the steps in this section. If that applies to you, you can use [our cloud-init file](https://git.coopcloud.tech/toolshed/abra/raw/branch/main/scripts/cloud-init/cloud-init.yaml). If your server has a public IPv6 address, you'll need to enable IPv6 on `docker_gwbridge` as well. See [this handbook entry](/operators/handbook/#enable-ipv6-on-docker_gwbridge) for more information.
 
 Otherwise, here are the step required:
 

mkdocs.yml

@@ -73,7 +73,9 @@ nav:
       - "Support Us": intro/support.md
   - "Maintainers":
       - maintainers/index.md
-      - "New Maintainers Tutorial": maintainers/tutorial.md
+      - "How to Become a Recipe Maintainer": maintainers/maintain.md
+      - "Package your First Recipe Tutorial": maintainers/tutorial.md
+      - "Recipe config upgrade checklist": maintainers/upgrade.md
       - "Packaging Handbook": maintainers/handbook.md
       - maintainers/catalogue.md
   - "Operators":
@@ -88,6 +90,7 @@ nav:
       - "Bylaws": federation/bylaws.md
       - "Finance": federation/finance.md
       - "Membership": federation/membership.md
+      - "Joining the Co-op Cloud Federation": federation/join.md
       - "Code of Co-operation": federation/code-of-coop.md
       - "Shared Infrastructure Inventory": federation/infra.md
       - "Proposals":
@@ -131,6 +134,7 @@ nav:
               - federation/resolutions/passed/033.md
               - federation/resolutions/passed/034.md
               - federation/resolutions/passed/036.md
+              - federation/resolutions/passed/038.md
           - "Stalled":
               - federation/resolutions/stalled/013.md
               - federation/resolutions/stalled/030.md