[feat] Multinode Guide So Far

Over a few sessions, @papiris:data.coop and I pooled our knowledge and experience into [this pad](https://pad.data.coop/SCAk4RQhRBy84SylWQehIQ?view). This commit creates a How-To Guide, describing what we know so far about multinode setups. Meaning: 1 or more manager node, with 1 or more worker nodes in a docker swarm.
2026-09-23 11:31:52 +02:00
32 changed files with 388 additions and 1116 deletions
@@ -36,7 +36,16 @@ In practice, this is what we currently rely on Swarm mode for.
 | Template driver | If you use `template_driver: golang` in your `compose.yml` to insert secrets or environment variables into your configs, then you are using a template driver. This feature has almost 0 documentation and does not appear to be supported by [the actual Compose Spec](https://github.com/compose-spec/compose-spec/blob/main/08-configs.md) and is actually completely blocked by `docker compose` ([source](https://github.com/docker/compose/blob/f9828dfab909e9dd0dd489a49088c8619ec2ca7e/pkg/compose/create.go#L1095)). Several recipes use this feature and it seems quite crucial for our usage. |
 | Stacks | Firstly, [a service](https://docs.docker.com/engine/swarm/how-swarm-mode-works/services/) is key concept here. A stack is then a shared namespace of services with networks, volumes, configs etc. The concept of a stack is a [unique](https://docs.docker.com/engine/swarm/stack-deploy/) to Swarm mode. Any replacement for Swarm mode would have to implement this kind of namespacing feature for backwards compatibility purposes. See [`psviderski/uncloud#94`](https://github.com/psviderski/uncloud/discussions/94) for more. |
 | Orchestration | When you run `abra app deploy`, we're running a slightly customised `docker stack deploy` under the hood. Swarm mode is supposed to automagically handle zero downtime updates and rollbacks if things fail. However, we're seeing [the limitations of this approach](/abra/swarm/#limitations). |
-| Multi-node | We are starting to see [the first signs](https://git.coopcloud.tech/toolshed/docs.coopcloud.tech/pulls/331) of multi-node installs. However, the majority of Co-op Cloud installs are single node. There is also a lack of [CSI](https://github.com/olljanat/csi-plugins-for-docker-swarm?tab=readme-ov-file) support for coordinating storage across multiple hosts when using Swarm mode. This means we kind of throw out [a bunch](https://docs.docker.com/engine/swarm/#feature-highlights) of the features of Swarm mode. The experiment is ongoing. |
+
+## *Maybe* unsupport matrix
+
+In practice, we don't see people in our community using Swarm mode for this.
+Please report in on `#coop-cloud-tech-future-brain:autonomic.zone` if you do
+use it! We could really use your input.
+
+| Feature | Explanation |
+| ----------- | ----------- |
+| Multi-node | The vast majority of Co-op Cloud installs are single node. There is a lack of [CSI](https://github.com/olljanat/csi-plugins-for-docker-swarm?tab=readme-ov-file) support for coordinating storage across multiple hosts when using Swarm mode, which means we kind of throw out [a bunch](https://docs.docker.com/engine/swarm/#feature-highlights) of the features of Swarm mode. However, there is growing interest in multinode setups and a push to improve our understanding. [Here's what we know so far, and some hints on getting started.](/operators/multinode) |

 ## Limitations

@@ -1,567 +0,0 @@
---
-title: NLNet CodeSupply
---
-
-# NLNet CodeSupply
-
-> Status: **pending** ([Link to open call](https://nlnet.nl/propose/))
-
-## System3: High Performance Scanner
-
-## Reference
-
- [`0x29a/hestia`](https://codeberg.org/0x29a/hestia)
-
-## Project Summary
-
-System3 is a generalization of a docker SBOM generation and security scanning
-tool called Hestia. It is intended to create a higher performance and more
-extensible alternative to ScanCode.io.
-
-Hestia is a proof of concept high speed, stand alone scanner for large numbers
-of docker images currently built to scan for vulnerabilities in the Co-op Cloud
-recipe catalog. This project will merge functionality from AboutCode to provide
-a more scalable alternative architecture to ScanCode.io and the scancode cli.
-
-The results of this project will be a Software Composition Analysis (SCA) tool
-that analyzes docker containers, produce SBOMs, and use those to identify
-vulnerable software. This vulnerability information will be enriched using open
-sources (such as EPSS). This proof of concept will be pluggable, making it easy
-to port scancode.io pipelines over to it.
-
-System3 is a reference to part of the cyberneticist Stafford Beer's Viable
-System Model.
-
-## Proposed effort
-
- Total cost: €30030.00
-
-## Explanation
-
-### Which tasks will you undertake, and (roughly) how much time/effort will each take?
-
-1.5 engineer weeks: Currently Hestia uses Syft and Trivy to build SBOMs and
-scan them for vulnerabilities. Over the course of this project, Syft will be
-replaced by AboutCode's container-inspector. Custom code fetching will be
-replaced with skopeo (what AboutCode's fetchcode-container plugin uses under
-the hood) to help identify missing or incorrectly specified docker images.
-AboutCode's packageurl-python will be used to generate PURLs for vulnerability
-identification. Where useful, AboutCode's commoncode will replace existing
-utilities. 
-
-(SPDX generation will use spdx-tools, rather than adopting ScanCode's custom
-implementation.)
-
-1.5 engineer weeks: PURLdb and Vulernable code databases will be used, if
-possible, to find vulnerabilities. If this works, they will replace Trivy as
-the scanner (though other tools may also be used to identify vulnerabilities).
-This accounts for both the exploration time and implementation (given
-feasibility). If this is not feasible, this time will also include a problem
-analysis.
-
-6 engineer weeks: Turning Hestia into System3 will also mean changing the
-underlying architecture. Currently a pipeline architecture passes messages
-between workers (analogous to ScanCode.io's pipes). This will be abstracted
-with a framework where worker functions advertise their capabilities using
-decorators, and interfaces and pipelines are specified using YAML. The actual
-queue management functionality will be abstracted so that worker developers
-simply need to understand the data model of their worker's domain and can
-ignore all other details of the system.
-
-This time accounts for framework design, implementation, usability experiments,
-and improvements based on feedback. 
-
-Additional work: Interspersed through the development process, I will be adding
-unit testing, property testing, and integration testing. This will all be run
-through continuous integration to detect breaking changes in upstream
-dependencies and bugs induced by code changes.
-
-### What hourly/daily/monthly rate did you use?
-
-€65/hr x 40 hour/week x 11 weeks = 28600 + 5% margin of error = 30030.00.
-
-### Will there be any expenses?
-
-There are no additional expenses.
-
-### Next Steps and Strech Goals:
-
-If I'm able to complete other tasks, I will add additional workers such as:
-
- A worker that connects to matrix and reports vulnerabilities to a chat
- A worker that files security issues based on SCA results against Gitea, Forjeo, or GitHub repositories
-
-As a fast follow, I also plan to build a tool that turns pipeline definitions
-into cloud pipelines using n8n and Terraform.
-
-### Comparison
-
-System3 will be most similar to ScanCode.io and the ScanCode toolkit CLI
-application.
-
-The ScanCode toolkit schedules jobs against the ScanCode.io server. The System3
-cli will simply be a scaled and stripped down version of the architecture,
-allowing it to run independently from the representation layer.
-
-ScanCode.io is a django web service that exposes a REST API and a web UI. The
-underlying pipeline data model tightly couples multiple unrelated concepts
-(such as django presentation). Failure to separate concerns degrades
-performance by increasing the context needed to execute operations, increasing
-the minimum lines of code involved in any pipeline, and by preventing efficient
-horizontal scaling (that is, scaling by component not scaling the entire
-platform). 
-
-Hestia already presents more clean separation of concerns that allows it to
-scale any individual component simply by increasing the number of worker
-threads. A queuing oriented design makes it possible to transition from threads
-in a single application, as it currently is, to a server-less architecture with
-minimal changes. With appropriate abstraction, workers can run locally as
-threads within a single application, or can be deployed to Scaleway Serverless
-Functions, OVHcloud managed Knative, AWS Lambda, Google Cloud Functions,
-Beam.cloud, Kubernetes with Knative/OpenFaaS/Fission, or other frameworks,
-without being completely rearchitected. When deployed to serverless platforms,
-horizontal scaling can be handled by the platform. Serverless bound to queues
-(such as RabbitMQ or SQS) is already a common architecture for systems that
-must support horizontal scaling.
-
-The failure to separate concerns also forces pipeline developers to understand
-the concept of a project and a pipeline, in order to implement a pipe. Hestia
-separates these concerns so that a worker simply needs to take input from a
-queue and write to another queue. 
-
-System3 will further abstract this so that pipelines can be written using a
-configuration language, like yaml or json, while workers are simply functions
-and classes that focus on input and output. Presentation is completely
-separated, reducing developer context and enabling more complexity in the way
-that views can be managed. The System3 proof of concept will implement the
-vulnerable code pipeline for docker containers.
-
-An enterprise, especially one focused on technology such as Microsoft, Amazon,
-or Google, may have thousands or millions of repositories, container images,
-and servers to assess. Downloading each container is simply infeasible, even
-for a project as small as Co-op Cloud with 2k docker images to scan. Hestia
-automates the work of downloading, caching SBOM artifacts, and cleaning up so
-that it doesn't run out of disk space. As I understand it, this requires
-additional external scripts to emulate in ScanCode.
-
-The failure to separate representation from the rest of the platform means that
-data processing workloads can impact the performance of the web interface.
-
-But the monolithic nature of ScanCode.io represents a larger missed opportunity
-at generalization. Scanning for vulnerabilities in repositories or containers
-can provide important security signals. These signals may be more appropriately
-processed within an open source SIEM/XDM such as Wazuh or an existing internal
-stack. Security signals don't need to be handled as a single atomic pipeline,
-but can be processed as a stream. Streaming events can allow continuous
-autonomous data enrichment, such as a vulnerability detected in a repository
-triggering a search against a data lake to identify potential deployed
-endpoints, then triggering dynamic vulnerability scanning against those
-endpoints.
-
-Why should a "project" be limited to things that can be represented as files?
-Why not a list of IP addresses used by workers running NMAP with NSE
-vulnerability detection scripts, producing vulnerability identification
-results, which could be enriched using the very same enrichment as SCA? Why
-should it not be possible to correlate vulnerabilities identified in SCA, SAST,
-build time DAST, or IAST reports, with each other to find gaps in the security
-process?
-
-With the right architecture, these problems are solved by implementing workers
-and wiring them into pipelines or writing new visualizations over data produced
-by these workers. That is the vision of System3. 
-
-### Technical (and other) Challenges
-
-There are three patterns my system needs to support:
-
- Queue with a single action. A worker consumes an item from the queue, processes the item, in serial.
- Pub/Sub. Work items are broadcast in parallel with no built-in mechanism for deduplication, allowing different types of work items to execute in parallel.
- Aggregation/Correlation. A work item may have several subtasks. Results of subtasks need to be collected up and correlated back to original projects. For example, a "recipe" (or application) has multiple versions, each version has multiple images, each image has multiple pieces of software, each piece of software may have multiple vulnerabilities. A worker needs to correlate vulnerabilities back to "recipes" at specific versions.
-
-There are two modes:
-
- Serial
- Batch
-
-There are two data source/sinks:
-
- Messages
- Data Lake
-  
-There are two target platforms:
-
- Local
- (host your own) Cloud
-
-Each of these, and the interaction between them, creates multiple opportunities
-for failure. The experience of the developer will be determined by how I
-balance exposing vs hiding detail. The more I obscure, the easier the system
-will be to use but the more limited it will be. This is often the key
-difference between enterprise tooling (where everything must be adapted to a
-wide range of scenarios) and small business tooling (where everything must be
-as simple as possible). 
-
-Due to character limitations, I've enumerated these challenges in more detail
-in the attached doc titled "Technical Challenges" (see below).
-
-### Ecosystem (max. 2000 characters)
-
-The tool will immediately be used by the Co-op Cloud project. Long term
-operational funding and management will be handled by the federation.
-Federation decisions are made democratically, via a resolution process. I'm
-actively coordinating with Co-op Cloud stakeholders and have attached a draft
-of the resolution 0XX (see below for draft) that describes the larger ecosystem
-within which this fits.
-
-One missing element is the security advisory announcement element (Co-op Cloud
-Security Advisory, or CCSA). Security advisory management is also a gap within
-the [AboutCode
-ecosystem](https://aboutcode.org/docs/getting_started/software-security/#manage-risk-with-aggregated-vulnerability-data).
-I will be writing a proposal for this as well, as I also have a proof of
-concept for it.
-
-Since I'm primarily using stable AboutCode libraries, coordination with
-AboutCode should not be necessary. If it is, I can use GitHub issues and the
-gliter channel (#aboutcode-org_discuss:gitter.im). During development I will
-probably join the VulnerableCode meeting to make sure I'm tracking the
-development of that project.
-
-However, the main users will likely be the Co-op Cloud project at the
-beginning. Once I can demonstrate that the system is stable and maintainable,
-it will make sense to expand to influencing AboutCode to consider integration
-opportunities. 
-
-## Background
-
-### Personal
-
-I have been a security engineer at Amazon (both the store and AWS) for almost
-10 years, and was a consultant to companies including Amazon and Microsoft for
-several years before that. During my time in AWS, I designed, built,
-operationalized, and drove adoption for a security testing framework now used
-by every AWS service and dozens of adjacent security teams. I designed a single
-framework that was easy for security engineers to develop, developers to
-onboard to and extend, and operators to maintain. The project was able to gain
-so much momentum, because I started by pulling in multiple stakeholders to
-understand the scope of the problem. 
-
-I have extensive experience with systems that must be highly performant. The
-tool I replaced was a DAST scanner. The scanner my tooling replace scanned a
-few dozen endpoints with 7 tests. My scanner ran dozens (and later hundreds) of
-tests against 16k endpoints, and did so in hours instead of days. I have
-implemented multiple orders of magnitude performance improvements to tooling
-more than once.
-
-I have developed other tooling as well, always bridging the gap between
-developers and security, always focused on making using the same toolkit for
-endpoint testing as build/integration testing. I have lead multiple consecutive
-successful programs to drive security improvement at scale at AWS. AWS is a
-highly technologically diverse environment. The combination of operating at
-scale against heterogeneous systems and previous work as a consultant has given
-me the diverse background I need to address similar problems globally. 
-
-## Other Funding (max. 1000 characters)
-
-There is currently no other funding for this project.
-
-## Attachments
-
-* [`technical_challenges.pdf`](./technical_challenges.pdf)
-* [`security_bus_design.pdf`](./security_bus_design.pdf)
-
-## Resolution 0XX Draft
-
-### Resolution 0XX: Security Event Management
-
- Deadline: Date
- Size: Medium
-
-#### Summary
-
-Create a federation wide Security Event Management process to address the
-following concerns:
-
- End users and security researchers need a mechanism to report security
-  vulnerabilities in Co-op Cloud maintained recipes
- Operators need to know if the version they are deploying or have deployed is
-  vulnerable, or if there are security related actions they need to take
- Maintainers needed to know if a recipe they maintain needs a(n emergency)
-  security update
-
-#### Details
-
-##### Background
-
-We have created a Co-op Cloud Security room on Matrix to coordinate on security
-improvements, and have discussed security concerns during kite flying on
-[2026-08-27](https://docs.coopcloud.tech/federation/kite-flying-pad-archive/#2026-08-27-12-utc),
-[2026-08-06-19](https://docs.coopcloud.tech/federation/kite-flying-pad-archive/#2026-08-06-19-utc),
-and
-[2026-07-30](https://docs.coopcloud.tech/federation/kite-flying-pad-archive/#2026-07-30-12-utc)
-(the later related to maturity models). We have also worked on at least one
-[document](https://cloud.klasse-methode.it/s/aNitMQjeo5QpHs4?dir=/&editing=false&openfile=true)
-outlining the security domains we are working within and to help focus on the
-most critical areas.
-
-Over the course of the past month, we have identified the most critical gaps as
-described by the following user stories.
-
-##### User Stories
-
- US1: As a Security Researcher, I have found a vulnerability in a Co-op Cloud
-  recipe. I would like to responsibly disclose this vulnerability to a Co-op
-  Cloud Security Contact so that users can be protected.
- US2: As an operator, I would like to be actively informed as soon as possible
-  when an exploitable vulnerability is detected in a recipe I am using so that
-  I can keep my end users safe.
- US3: As an operator, I would like to be able to find out if any recipes I'm
-  currently using have known vulnerabilities so that I can upgrade them in
-  order to keep my customers safe.
- US4: As a maintainer, I would like to be informed of vulnerabilities in
-  recipes I maintain so that I can update recipe definitions and tell consumers
-  to upgrade.
- US5: As an operator or maintainer, I would like to be able to run my own
-  vulnerability scans to identify new vulnerabilities so that I can keep ahead
-  of security team latency. Vulnerability scanners tend to produce a lot of
-  noise, so I'd like to be able to leverage security team pre-filtering for all
-  *known* issues so that I can focus on only *net new* issues.
-
-##### Co-op Cloud Security Advisories (CCSA) feed
-
-Security advisories are the foundation of any project's security program. They
-allow a project to announce security events, including, but not limited to,
-vulnerabilities that require upgrades, security incidents such as compromised
-hosts, and security program changes.
-
-The primary function of an advisory is to fulfill US2 by announcing
-vulnerabilities as soon as there are actions that an end user can take to
-mitigate the issue.
-
-Feeds generally come in the form of an email list. Often the email list is
-replicated to an RSS for easier tracking.
-
-Within the Co-op Cloud recipe set, there are currently known issues with
-recipes. Unfortunately the current way to alert users is to post in the general
-channel. This is easy to miss and is not easily searchable.
-
-The creation of a CCSA email list and RSS feed allows operators to quickly
-learn about issues, as information becomes available, without needing to filter
-through other chatter. With an RSS feed, additional automation (such as a
-Matrix bot) becomes significantly easier.
-
-##### Co-op Cloud Security Advisories (CCSA) catalog and Abra Integration
-
-While email/RSS can fulfill US2, a catalog can help fulfill UC3. CCSA can be
-written using a simple format such as yaml, toml, or json (so they can be
-searched based on recipe, CVE, or other metadata), and output to email, RSS,
-and a json vulnerability catalog. Such a catalog can be easily searched using
-automated tooling, can be rendered into a searchable page, or can be integrated
-into the abra deployment tool.
-
-One specific request that multiple operators have repeated is for some kind of
-"abra vulnerability check." This is a sequence diagram for populating feeds and
-catalogs:
-
-```
-,--.                  ,---------.                                 ,-----. ,-------. ,----.
-|SE|                  |CCSA tool|                                 |email| |catalog| |feed|
-`-+'                  `----+----'                                 `--+--' `---+---' `--+-'
-  | security advisory tml  |                                         |        |        |
-  |- - - - - - - - - - - ->|                                         |        |        |
-  |                        |                                         |        |        |
-  |                        | send from ccsa@security.coopcloud.tech  |        |        |
-  |                        |---------------------------------------->|        |        |
-  |                        |                                         |        |        |
-  |                        |     build security.coopcloud.tech/ccsa.json      |        |
-  |                        |------------------------------------------------->|        |
-  |                        |                                         |        |        |
-  |                        |        publish to security.coopcloud.tech/rss.xml|        |
-  |                        |---------------------------------------------------------->|
-  |                        |                                         |        |        |
-,-+.                  ,----+----.                                 ,--+--. ,---+---. ,--+-.
-|SE|                  |CCSA tool|                                 |email| |catalog| |feed|
-`--'                  `---------'                                 `-----' `-------' `----'
-```
-
-Once in a catalog, a user could run abra to test their own servers:
-
-```
-,----.                     ,----.                     ,----------. ,---------.
-|user|                     |abra|                     |swarm host| |ccsa.json|
-`--+-'                     `--+-'                     `-----+----' `----+----'
-   |     abra sec_check       |                             |           |
-   |- - - - - - - - - - - - ->|                             |           |
-   |                          |                             |           |
-   |                          |         get recipes         |           |
-   |                          |- - - - - - - - - - - - - - >|           |
-   |                          |                             |           |
-   |                          | deployed recipe/image list  |           |
-   |                          |< - - - - - - - - - - - - - -|           |
-   |                          |                             |           |
-   |                          |         download if not cached          |
-   |                          |- - - - - - - - - - - - - - -|- - - - - >|
-   |                          |                             |           |
-   |                          |          check against recipes          |
-   |                          |- - - - - - - - - - - - - - -|- - - - - >|
-   |                          |                             |           |
-   |                          |           vulnerable matches|           |
-   |                          |< - - - - - - - - - - - - - -|- - - - - -|
-   |                          |                             |           |
-   | list of vulnerable apps  |                             |           |
-   |< - - - - - - - - - - - - |                             |           |
-   |                          |                             |           |
-,--+-.                     ,--+-.                     ,-----+----. ,----+----.
-|user|                     |abra|                     |swarm host| |ccsa.json|
-`----'                     `----'                     `----------' `---------'
-```
-
-Here are command line mockups to help communicate the UX..
-
-Check one host, find vulnerabilities:
-
-```
-$ abra ccsa_check example.coopcloud.tech 
-Downloading latest Co-op Cloud Security Advisories
-|================================================| 100%
-Checking........ complete!
-[thisapp.example.coopcloud.tech]
-CRITICAL: RCE in ThisApp 1.2.3+3.4.5 -> ThisApp 1.2.4+3.4.6
-        CVE-4321-12345, CVE-2033-12346, CVE-2033-12347
-        https://security.coopcloud.tech/CCSA-20260914-2.html
-[thatapp.example.coopcloud.tech]
-WARNING: Denial of Service ThatApp 3.2+2.2.3
-        CVE-4321-12111
-        https://security.coopcloud.tech/CCSA-20260914-6.html
-```
-
-Check for vulnerabilities across all managed hosts:
-
-```
-$ abra server ls -m
-[{"host":"foo.coopcloud.tech","name":"foo"},
-{"host":"bar.coopcloud.tech","name":"bar"}]
-
-$ abra ccsa_check example.coopcloud.tech --all
-Using cached Co-op Cloud Security Advisories 
-Checking...
-foo
-bar
-...complete!
-
-[thisapp.foo.coopcloud.tech]
-CRITICAL: RCE in ThisApp 1.2.3+3.4.5 -> ThisApp 1.2.4+3.4.6
-        CVE-4321-12345, CVE-2033-12346, CVE-2033-12347
-        https://security.coopcloud.tech/CCSA-20260914-2.html
-[thatapp.foo.coopcloud.tech]
-WARNING: Dangerous configuration in OtherApp 332.1+1.2.3
-	    Read advisory to make sure this deployment isn't vulnerable
-        https://security.coopcloud.tech/CCSA-20260914-6.html
-[bar.coopcloud.tech]
-No vulnerabilities detected!
-```
-
-CCSA can provide a mechanism to alert users about issues outside of just CVEs.
-Supply chain attacks could poison docker images, requiring upgrades or
-downgrades for images downloaded during certain times. Compromise of member
-accounts could result in malicious code in abra or other tools. A CCSA can
-provide a key outlet for incident response actions that require public
-reporting.
-
-##### Maintainer
-
-In order to be able to provide updates to fulfill UC2 and UC3, we first need to
-have actionable information. It isn't enough to tell an operator that an
-application has a vulnerability if they can't do anything about it.
-Unactionable information manifests apathy. We must have a clear path from
-vulnerable to (more) secure.In most cases, this will require working with a
-recipe maintainer to upgrade a recipe to a version that isn't vulnerable.
-
-Unfortunately, there is no automated mechanism to identify a recipe maintainer
-point of contact. There are few acceptable options for this:
-
-1. Include a maintainer contact (email or matrix id) in the recipe.
-2. Include a link to a maintainer support matrix channel.
-3. Create a matrix channel in the coop cloud space for maintainers.
-4. create a mailing list for maintainers.
-
-Option 1 is optimal since it provides the highest level of ownership and
-accountability. Option 2 makes a support rotation easier and more accessible,
-but has no clear and specific point of contact. Option 3 is not optimal since
-it would be a bit noisy. Option 4 would also make a support rotation easier (as
-option 2) but would make it harder to find a specific person during a security
-event.
-
-##### Reporting Contact
-
-Today we are able to identify new security issues. Once a new vulnerability is
-identified within a recipe, someone needs to triage the vulnerability. This
-includes reading the description, understanding how it does or does not impact
-the specific image and associated network as deployed via the recipe, and
-determining the level of additional actions.
-
-For important vulnerabilities, maintainers need to be alerted. Someone needs to
-coordinate with those maintainers to make sure there's a safe upgrade path.
-Someone needs to write up a security advisory
-([demo](https://0x29a.codeberg.page/CCSA-DEMO/), publish that advisory, and,
-optimally, answer questions related to the advisory.
-
-This is part of the work of a Security Analyst in the field of Vulnerability
-Management. This needs to be staffed in accordance with our event response
-time. This doesn't need to be a task that takes up all someone's time, but
-there do need to be contacts in various time zones to be able to respond in
-case something comes up.
-
-##### VEX
-
-Triage work can be recorded using the Vulnerability Exploitability eXchange
-format (VEX). By also publishing this information as we review findings, we can
-coordinate with operators who may wish to run their own scans, or who are doing
-internal security work. We may also want to consume VEX from operators or other
-analysis teams. Hestia does not currently support VEX ingestion, but Trivy
-does. Code and infrastructure adjustments to hestia could allow authorized
-users to coordinate on vulnerability management.
-
-##### Recommendations
-
-1. Create a "Security@" email mailing list to which coop members and authorized
-   security engineers can subscribe.
-2. Repurpose the existing "Security" room for public (operator, maintainer, and
-   external) facing security support.
-3. Create a "Security Team" room in the "Co-op Cloud" matrix space specifically
-   for people working on security problems (triaging, security engineering,
-   etc).
-4. Allocate infrastructure (two swarm hosts, one subdomain) for security team
-   related work and testing.
-5. Create a "scanner" bot ([PoC here](https://codeberg.org/0x29a/hestia)) to
-   find new vulnerabilities for triage. Run this daily, increase to hourly if
-   needed.
-6. Create a matrix bot for the "Security Team" room to alert on new
-   vulnerabilities.
-7. Create a "Recipe Maintainer" room specifically for identifying maintainers
-   to coordinate with.
-8. Create a "support" object for each recipe entry in "recipes.json" a. Add a
-   (mandatory) "maintainer" field to this support object to identify a
-   maintainer contact (could be a mailing list maintainers are on). b. Add an
-   (optional) SLA field to the "support" field that lists the maintainer
-   response time. c. Decrease the "status" to "basic" for all recipes that lack
-   the support object. d. Decrease the "status" to "ok" for all recipes that
-   lack an SLA or for which the SLA has been missed in the last month.
-9. Create a security.coopcloud.tech subdomain for security related information
-   b. link from docs.coopcloud.tech to security.coopcloud.tech a. list security
-   contact information here
-
-##### Follow up
-
-1. Consider compensating maintainers of recipes with low SLAs and high scores
-2. Determine how to staff Triage team
-3. Apply for funding from nlnet to staff the security team for the first year.
-4. Create generic incident response plans for different incident types
-5. Identify an appropriate security contact method
-
-```
-// Security contact - email, matrix chat, list on website
-// Security feed - Co-op Cloud Security Advisory
-// -- mailing list, RSS feed
-//
-// Security management team
-```
@@ -1,269 +0,0 @@
---
-title: NLNet Restack
---
-
-# NLNet Restack
-
-> Status: **Not submitted, missed the deadline, will submit in January 2027** ([Link to open call](https://nlnet.nl/propose/))
-
-# Select a fund
-
-## Which of our funds are you applying for?
-
-Restack.
-
-# Project overview
-
-## Proposal title
-
-Scaling the Co-op Cloud Software Commons.
-
-## Project website(s) / repositories
-
- [coopcloud.tech](https://coopcloud.tech)
- [docs.coopcloud.tech](https://docs.coopcloud.tech)
- [`git.coopcloud.tech/toolshed/abra`](https://git.coopcloud.tech/toolshed/abra)
- [`git.coopcloud.tech/toolshed/alakazam`](https://git.coopcloud.tech/toolshed/alakazam)
-
-## Please summarise the proposed project and its expected results in a few lines. (max. 1000 characters)
-
-Co-op Cloud is a software commons, international federation and broad solidarity network which works towards a vision of democratic technology for everyone.
-
-We focus here on the software commons: a suite of tools and shared configs which simplify the deployment and maintenance of free software apps. Co-op Cloud implements a "pragmatic restack" where the needs of small-scale hosting collectives are the central driving force.
-
-This approach has lead to considerable decentralised growth and international adoption with an estimated 50-100 active operators, 20-40 hosting collectives, thousands of end-users, 21 federation members and successful commercial projects built on top of Co-op Cloud.
-
-This growth pushes our implementation to its limits, revealing issues in implementation (maintenance, technical debt), performance, missing distributed collaboration and operational features. In this project, we aim to overcome these limitations and continue scaling the Co-op Cloud software commons.
-
-# Proposed effort
-
-## How much money do you request for your project? (In Euros. Between € 5 000 and € 50 000 for a first grant.)
-
-47880 EUR.
-
-## Please provide a breakdown clarifying how the requested budget would be used. Which tasks will you undertake, and (roughly) how much time/effort will each take? What hourly/daily/monthly rate did you use? Will there be any expenses? (max. 4000 characters)
-
-We propose an hourly rate of 60 EUR per hour with a total of 798 dev hours (breakdown below per heading). We anticipate no expenses. Please see attached work.pdf for more.
-
-Maintenance & Technical Debt (233 hours)
-
- Fix the oustanding (as of Nov 2026) 21 bugs in Abra reported by operators. These issues represent daily friction for operators and make deployment, maintenance and collaboration work more difficult to carry out.
-
- Upstream our patches to Docker CLI and upgrade to the latest Docker libraries in Abra so that we maintain parity with upstream developments.
-
- Migrate from the incomplete xgettext-go to the official upstream Golang xgettext.
-
- Migrate to the new compose-go standard library in Abra so that we maintain parity with one of the central open standards which we rely on. This decouples our sole reliance on the Docker Swarm runtimes (out-of-date) implementation of the Compose Specification.
-
-Performance (100 hours)
-
- The Co-op Cloud catalogue is a single JSON file which is becoming a performance bottleneck for Abra. We will convert catalogue generation and querying into a lightweight API service which always provides fast results regardless of quantity of app configs which integrates with Abra.
-
- Abra development follows the "make it work, make it right, make it fast" principle. We are now in the "make it fast" phase. Abra requires profiling to understand where it is doing double work and unecessary bookkeeping. The goal is to return to a high speed CLI experience.
-
-Distributed Collaboration & Operations (450 hours)
-
- Co-op Cloud currently "takes over" an existing server, imposing a single web proxy choice. Operators need proxy agnosticism, supporting several popular proxies seamlessly (e.g. Traefik, Nginx, Caddy).
-
- App configs rely on a ".env" file format (FOO=BAR). This format was chosen for interoperability but with the increase of config options, these files become difficult to manage. We will migrate to a YAML configuration for maintainers which brings new organisation benefits while keeping the .env file for operators.
-
- When maintainers upgrade app configs, changes must be propagated to operator configs (e.g. a new config knob for database perf). This is currently a manual process. We will implement an automatic upgrade in Abra with a change overview for operators.
-
- With the development of the new Docker Secrets Engine, it is possible to decouple the secret injection of Abra from the Docker Swarm runtime. Implementing secret engine support in Abra would reduce our reliance on the Docker runtime overall due to its pluggable interface with independent secret management tools.
-
- Due to increasing numbers of app config maintainers, there are more pull request review workflows. The Abra app config upgrade and release functionality does not conveniently support a pull request workflow. We will implement this workflow support in Abra by allowing Abra to produce and adapt to diffs which are designed for a review, approve and apply workflow.
-
- Co-op Cloud operators sync their app config changes manually using Git (e.g. deployment version). We will implement a peer-to-peer sync in Abra which allows operators to inform each other about deployment and maintenance operations directly on the command-line. We aim to implement this using p2panda-go (Iroh underneath).
-
- Alakazam is a longrunning prototype used by KolliCloud (free software hosting platform built on Co-op Cloud) which implements a wrapper of Abra and supports the deployment of multiple apps in a single "stack" (e.g. deploy Nextcloud, BigBlueButton and Rauthy SSO with shared config). It has reached maturity and been adopted by the Co-op Cloud federation as an official community tool. There is a desire to bring the feature set of Alakazam back to Abra, ending the "wrapper of a wrapper" prototype implementation and giving all Co-op Cloud operators first-class support for seamless "stack" deployments without needing an additional tool.
-
-## Please compare your own project with other relevant efforts (both existing and historical). What is new, more thorough or otherwise different? Have you considered contributing to any of the others? (max. 4000 characters)
-
-The Co-op Cloud implementation is based upon lessons learnt while participating in the Cloudron, YunoHost and Ansible projects (Co-op Cloud maintainers were active Ansible, Molecule and YunoHost maintainers in the past).
-
-Cloudron repackages apps in a custom format, duplicating work and became source-available. YunoHost relies too closely on the distribution cycle of Debian and does not make use of containerisation which tends towards "house of cards" server installs which must work around the OS (e.g. managing custom PHP versions outside the Debian distribution cycle).
-
-Ansible proposes a model of re-use which is not reflected in reality, resulting in the same basic roles being developed over and over again. Solutions for role testing such as Molecule and Ansible Collections have not truly alleviated the situation. We believe Ansible is not flexible enough to allow for deployment specifics and broad config collaboration amongst multiple hosting collectives.
-
-Kubernetes helm charts overlaps in focus but Co-op Cloud participants have long rejected Kubernetes (including distros which try to simplify k8s) as overkill and unsuitable for the needs, capacities and means of small-scale hosting collectives. Charts also duplicates work with a custom packaging format.
-
-Nix and NixOS as a deploy and config management platform has seen minor adoption in the Co-op Cloud community but ultimately lacks the focus on day 1 and 2 operations that Abra and Alakazam bring to Co-op Cloud operators. Nix proposes once more a custom app packaging format which require duplicated effort or the complexity of a "compose2nix" layer. It has a steep learning curve and a significant "lock in" factor, making it difficult to share tools outside of the Nix ecosystem.
-
-Uncloud is an upcoming solution to "docker compose in production" but also duplicates work with a custom app packaging format. We are watching closely how Uncloud rejects the declarative approach of the Swarm runtime in favour of a imperative model. Uncloud emerged in 2026, 6 years after the start of Co-op Cloud.
-
-We maintain a comparisons list (docs.coopcloud.tech/intro/comparisons) to establish the position of Co-op Cloud in this fast moving field of deployment and config management. We still believe Co-op Cloud offers a unique software solution for the problem at hand.
-
- We re-use upstream packaging efforts of free software developers and meet them where they are at: the compose standard. All app configs form our config commons which can be re-used by any tool which consumes the compose standard (e.g. Guix ports have been attempted).
-
- We realise real "should to shoulder" collaboration on free software app configs with the flexibility of the compose standard. A hosting collective of 2 hackers and another of 200 hackers can work in the same app config without crashing into each other with each deploying a config which is radically customised for their specific situation. Their respective maintenance work contributes back to each other and the greater software commons.
-
- One of the major strengths of Co-op Cloud is its relative familiarity and simplicity for (new) operators in comparison to other tools. Abra follows the Docker CLI design closely and there is limited indirection and abstraction: it's images and compose files underneath and that's it.
-
- The Co-op Cloud federation is a democratically run international (semi-formal) organisation of 21 small-scale hosting collectives which is open for all to participate and serves as the engine of continuity for the software commons. This offers a level of confidence for the Co-op Cloud project because it is not reliant on a single "benevolant dictator" or hosting collective and it is resilient due to the decentralised governance model: we do not need to repeat the A/I situation - if one collective is taken down, another will take its place because the underlying structure is not disrupted: the software commons, federation and solidarity network.
-
-## What technical challenges do you expect during the project? (max. 4000 characters)
-
-Co-op Cloud faces an immense challenge in overcoming the limitations of the "pragmatic restack" approach and the resulting path dependency: the reliance on the Docker Swarm runtime, an increasingly underdeveloped software for container orchestration. This is not an immediate emergency but remains something we work towards resolving in this project work and beyond.
-
-An estimated 20-40 hosting collectives now rely on Co-op Cloud and we cannot deliver a breaking platform migration such as a new container orchestration engine which would disrupt their daily operations. We have analysed this dependency (docs.coopcloud.tech/abra/swarm) and see a path forward: we slowly strip away our dependency on specific parts of Swarm (e.g secret management, templating and finally orchestration) and swap them out with resilient alternatives, migrating our entire ecosystem forwards in a backwards compatible manner, leaving nobody behind.
-
-One concrete example is the development of the new Docker Secrets Engine which will allow us to implement a plugin architecture for secrets delivery based on the choice of secret management tool of the operators themselves. This implementation represents a challenge for us because it is the first time we will undertake such an ecosystem-wide migration. This is included in the proposed work items of this proposal.
-
-The Co-op Cloud federation represents a diverse spectrum of use cases, some demanding highly constrained deployments (offline-first, single-board computers, intermittent electricity) and others requiring high throughput (increasing userbases, heavier and more powerful free software apps, specialised deployments and collaboration features). The development of fixes and new features must pass through this collective consensus, improving and becoming the exact feature scope which benefits all participants, including end-users. This involves many technical discussions and redesigns to reach the final result.
-
-Co-op Cloud faces a new technical challenge in recent times. The project was developed for small-scale hosting collectives that already "know what they're doing" but the pragmatic accessibility of our tools has increasingly attracted new system administrators and emerging hosting collectives, some of whom have never even used the command-line before. This is a new use case which we must bring into our design thinking and implementation of our tools and documentation writing.
-
-Co-op Cloud tools have also become "officially" international since the Sepal Fund application from the Abya Yala Network in which we delivered a Spanish translation for Abra with full command-line coverage (options, docs, command output, etc.) and integration with a self-hosted Weblate deployment.
-
-This has been a great success but demands more internationalisation. This process challenges the limits of most free software projects approach to internationalisation. We have been forced to rely on an incomplete implementation of xgettext which we must migrate away from and even one of the most popular CLI Golang libraries (spf13/cobra) requires patching to deliver translated option flags. This requires us to make upstream contributions which are often hard to implement and deliver due to how deep reaching they are in the upstream implementation (implementing i18n in a codebase touches nearly everything).
-
-## What is the ecosystem around your own project, and how will you engage relevant actors? For example, does your project depend on other projects/people? And who would be the main users? (max. 2000 characters)
-
-The Co-op Cloud federation and solidarity network remains the primary ecosystem in which our project takes place. We congregate online in our Matrix community, publish through the Fediverse, share community updates on the Co-op Cloud blog (coopcloud.tech/blog) and by participating at events, doing workshops and presentations. End-users are included through their interaction with federation members on the local level. Federation members are currently based in Latin America, Australia, North America and Europe.
-
-Based on a usage survey conducted in October 2026, over 70% of Co-op Cloud participants offer paid free software services to customers. 2/3 of those are "small", serving less than 10 customers and 1/3 are "medium to large", serving 101-1000 customers. Here are some highlights of the most significant federation member projects:
-
- KolliCloud, a free software hosting platform built by Local-IT on top of Co-op Cloud serves, amongst others, Germany’s largest queer youth support organisation queersupport.de.
-
- Escuela Común, a hands-on self-organised school for emerging indigenous hosting collectives based in Latin America has seen 21 instances of Co-op Cloud deployed and managed by communities themselves with the emergence of 2 public media networks based on Peertube in Argentina and El Salvador.
-
- Merri-bek Tech, recently featured in ABC News as "a grassroots plan to reclaim the internet from 'big tech'" approaches climate resiliency from a "neighbourhood first" approach, incorporating Co-op Cloud as it's foundation in LoRes Mesh while building resilience features alongisde with peer-to-peer systems such as p2panda.
-
- Popular free software projects such as Bonfire, Karrot and Lauti have joined the federation and adopted Co-op Cloud as one of their foundational deployment options. This has lead to broader usage of Co-op Cloud in the case of more visible deployments such as jacobin.social (Bonfire hosting via CoQuest, also a federation member).
-
-# Background
-
-## What makes you the right person(s) for this effort? Do you have relevant experience in this or other projects/organisations? And if so, can you tell us a bit about your contributions? (max. 2000 characters)
-
-(Redacted)
-
-## Does (or did) the project have other funding sources? (max. 1000 characters)
-
-Co-op Cloud has received 32,986 EUR from the European Cultural Fund in 2022, 9,240 GBP from a private funder in 2023 and receives up to three years of financial support (~5000 USD) via The Sepal Fund since 2025.
-
-Local-IT, a Co-op Cloud federation member based in Germany has received 540,000 EUR in public funding to build KolliCloud, a free software hosting platform built on Co-op Cloud.
-
-The Co-op Cloud federation has developed a membership model which funds 5-10 hours of software development and maintenance work a month. Member fees have also funded social processes such as organising the community "walk-in" Kite-flying hours and a year long position for a financial administrator for the federation.
-
-The Co-op Cloud federation receives donations via Open Collective for providing public internet services (e.g. git.coopcloud.tech which provides also free CI/CD) to members of our community who are not members of the federation.
-
-# Attachments
-
-## Attachments are not needed. Please ensure the proposal is self-contained. But in case you have supplementary material you wish to share (e.g. spreadsheets, diagrams, endorsements), you can do so here. (As HTML, PDF, ODF, images or plain text. Max 50 MB in total.)
-
-Links to specific work items, more context and a brief budget explanation.
-
-## Budget
-
-Estimation system used:
-
- Small: 5-20 dev hours
- Medium: 20-40 dev hours
- Large: 40-80 dev hours
-
-Times and totals are included below. Final totals are included at the end.
-
-## 1) Maintenance & Technical Debt
-
-> Fix the oustanding (as of Nov 2026) 21 bugs in Abra reported by operators. These issues represent daily friction for operators and make deployment, maintenance and collaboration work more difficult to carry out.
-
-All outstanding 21 `abra` bugs as of November 4 2026: [link](https://git.coopcloud.tech/toolshed/abra/issues?q=&type=all&state=open&labels=330&milestone=0&assignee=&poster=).
-
-We estimate an average of 8 hours per bug, small. 8 hours * 21 = 168 hours.
-
-> Upstream our patches to Docker CLI and upgrade to the latest Docker libraries in Abra so that we maintain parity with upstream developments.
-
-Here is our [`docker-cli` patch](https://git.coopcloud.tech/toolshed/abra/src/commit/550c9aa48fcdb587e03d43cceb261018095ff6ed/go.mod#L155) which we would like to upstream. The change has to do with allowing multiple protocols ingress on a single port. This is a known issue in upstream and we believe it needs more social pressure applied to be merged and released.
-
-We estimate 20 hours, medium.
-
-> Migrate from the incomplete xgettext-go to the official xgettext Golang bindings.
-
-Here is the specific issue which deals with the need to migrate to upstream `xgettext` for a complete native implementation  which supports Go: [link](https://git.coopcloud.tech/toolshed/abra/issues/688).
-
-We estimate 30 hours, medium.
-
-> Migrate to the new compose-go standard library in Abra so that we maintain parity with one of the central open standards which we rely on. This decouples our sole reliance on the Docker Swarm runtimes (out-of-date) implementation of the Compose Specification.
-
-Here is the issue which outlines the limitations we face by not migrating away from the (out-of-date) Docker Swarm implementation of the Compose standard: [link](https://git.coopcloud.tech/toolshed/abra/issues/492).
-
-We estimate 30 hours, medium.
-
-**TOTAL**: 248 hours
-
-## 2) Performance
-
-> The Co-op Cloud catalogue is a single JSON file which is becoming a performance bottleneck for Abra. We will convert catalogue generation and querying into a lightweight API service which always provides fast results regardless of quantity of app configs which integrates with Abra.
-
-Here is the general outline of an implementation which we would like to bring forward: [link](https://git.coopcloud.tech/toolshed/almanac).
-
-We estimate 60 hours, large.
-
- Abra development follows the "make it work, make it right, make it fast" principle. We are now in the "make it fast" phase. Abra requires profiling to understand where it is doing double work and unecessary bookkeeping. The goal is to return to a high speed CLI experience.
-
-This work requires investigation and the establishment of what is feasible to fix within this work item.
-
-We estimate 40 hours, medium.
-
-**TOTAL**: 100 hours
-
-## 3) Distributed Collaboration and Operations
-
-> Co-op Cloud currently "takes over" an existing server, imposing a single web proxy choice. Operators need proxy agnosticism, supporting several popular proxies seamlessly (e.g. Traefik, Nginx, Caddy).
-
-Proxy agnosticism: [link](https://git.coopcloud.tech/toolshed/organising/issues/686), Related issue: [`#388`](https://git.coopcloud.tech/toolshed/organising/issues/388)
-
-We estimate 60 hours, large.
-
-> App configs rely on a ".env" file format (FOO=BAR). This format was chosen for interoperability but with the increase of config options, these files become difficult to manage. We will migrate to a YAML configuration for maintainers which brings new organisation benefits while keeping the .env file for operators.
-
-The new YAML format for free software app config maintainers: [link](https://git.coopcloud.tech/toolshed/organising/issues/695)
-
-We estimate 60 hours, large.
-
-> When maintainers upgrade app configs, changes must be propagated to operator configs (e.g. a new config knob for database perf). This is currently a manual process. We will implement an automatic upgrade in Abra with a change overview for operators.
-
-Propagating app config changes to operators automatically: [link](https://git.coopcloud.tech/toolshed/abra/issues/504)
-
-We estimate 40 hours, medium.
-
-> With the development of the new Docker Secrets Engine, it is possible to decouple the secret injection of Abra from the Docker Swarm runtime. Implementing secret engine support in Abra would reduce our reliance on the Docker runtime overall due to its pluggable interface with independent secret management tools.
-
-No issue has been created for this beyond a growing consensus in the "Research & Development" community chat the secrets engine migration could be our first step to begin the migrating away from Docker Swarm. This work item requires working closely with federation members to understand our first plugin implementation and backwards compatible migration path forward within the app configs. The Pass CLI tool is commonly used by federation members for secret management and represents a simple target for this item.
-
-We estimate 80 hours, large.
-
-> Due to increasing numbers of app config maintainers, there are more pull request review workflows happening on git.coopcloud.tech. The Abra app config upgrade and release functionality does not conveniently support a pull request workflow. We will implement this workflow support in Abra by allowing Abra to produce and adapt to diffs which are designed for a review, approve and apply workflow.
-
-Here is the issue: [link](https://git.coopcloud.tech/toolshed/abra/issues/806)
-
-We estimate 30 hours, medium.
-
-> Co-op Cloud operators currently sync their app config changes manually using Git (e.g. deployment version). We will implement a peer-to-peer sync in Abra which allows operators to inform each other about deployment and maintenance operations directly on the command-line. We aim to implement this using p2panda-go (Iroh under the hood).
-
-This is a longrunning thread over the years which has recently been resurrected: [link](https://git.coopcloud.tech/toolshed/abra/issues/809). This discussion is not finished and does not represent the "third way" of moving away from Git as data store and using p2panda as peer-to-peer sync strategy.
-
-We estimate 80 hours, large.
-
-> Alakazam is a longrunning prototype used by KolliCloud (free software hosting platform built on Co-op Cloud) which implements a wrapper of Abra and supports the deployment of multiple apps in a single "stack" (e.g. deploy Nextcloud, BigBlueButton and Rauthy SSO with shared config). It has reached maturity and been adopted by the Co-op Cloud federation as an official community tool. There is a desire to bring the feature set of Alakazam back to Abra, ending the "wrapper of a wrapper" prototype implementation and giving all Co-op Cloud operators first-class support for seamless "stack" deployments without needing an additional tool.
-
-This effort has been decided by on federation members in [`R037`](https://docs.coopcloud.tech/federation/resolutions/passed/037/). The exact feature set needs to be drawn up and a design for how these features will be merged into Abra will also need to be published and agreed upon. The Alakazam feature set is stable since years, so we believe this should not be a moving target.
-
-We estimate 100 hours, large.
-
-**TOTAL**: 450 hours
-
-## Final totals
-
-* 248 + 100 + 450 = 798 total hours
-* 798 * 60 EUR hourly rate = 47880 EUR
-
-# AI disclosure
-
-## Did you use generative AI in writing this proposal?
-
-No.
-
-## Does your project build on an existing codebase that already includes, or expects to gain, a significant amount of code generated by AI?
-
-No.
@@ -0,0 +1,19 @@
+---
+title: Organising handbook
+---
+
+## Where do I find "the community"?
+
+The main place is the [Matrix community chat channels](/intro/contact/#matrix). You'll find a number of folks who are actively interested in the project and/or using `abra` and some of our recipes. Furthermore, Matrix has an excellent network of Cool People :tm: and in practice we've e-met a lot of groups who are interested in Co-op Cloud.
+
+## Onboarding new project members
+
+We still haven't worked this out. We're working on it.
+
+## Gathering new case studies
+
+We try to gather as many "case studies" as possible, stories & concrete examples of Co-op Cloud being used For Good :tm: See [coopcloud.tech](https://coopcloud.tech) for our existing examples. These studies help people identify what the purpose of the project is.
+
+## Monthly updates
+
+We have decided we'll try to do monthly progress updates. These will be published on the Co-op Cloud blog. It's a pretty loose format and we're basically just copy/pasta'ing things to a public pad during the month: ["This month in Co-op Cloud"](https://pad.autonomic.zone/YHKn4vHORmS6wjN1t2zi5A?both). Feel free to add your items to the monthly agenda and they will be included! All the previous posts can be seen [here](https://coopcloud.tech/blog/).
@@ -1,16 +1,7 @@
 ---
-title: Inventory
+title: Shared Infrastructure Inventory
 ---

- [Public documentation](https://docs.coopcloud.tech/federation)
- [Git hosting](https://git.coopcloud.tech/)
- [Matrix Space](https://matrix.to/#/#coop-cloud-space:autonomic.zone)
- [Website](https://coopcloud.tech/)
- [Single Sign On](https://translate.coopcloud.tech/)
- [Translation](https://translate.coopcloud.tech/)
- [Sheets and time tracking](https://sheets.coopcloud.tech/)
- [Drone CI/CD](https://build.coopcloud.tech)
-
 ## Shared repository for fedi maintainers

 > [coop-cloud-apps](https://git.coopcloud.tech/toolshed/coop-cloud-apps)
@@ -1,5 +1,5 @@
 ---
-title: Join the CCF
+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.
@@ -4,27 +4,27 @@ title: Membership

 > 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 | Status   |
-| --------- | --------- | -------- |-------- | -------- |
-| [Agaric](https://agaric.coop/) | ⭕ | - | `@wolcen:matrix.org` | Paused  |
-| [Autonomic](https://autonomic.zone) | ⭕ | - | `@kawaiipunk:autonomic.zone` | Active  |
-| [Bonfire](https://bonfirenetworks.org) | ✅ | - | `@mayel:matrix.org`) | Active  |
-| [Bunk Computer Cooperative](https://bunk.computer) | ✅ | - | `@maren@bunk.computer` | Active  |
-| [CoQuest - IT Coop Stuttgart](https://coquest.coop/en) | ✅ | voting rights waived | `hallo@coquest.coop` | Active  |
-| [Democratic Tech Fund](https://democratictech.fund/) | ✅ | - | `@mike_hales:matrix.org` | Active  |
-| [Doop.coop](https://doop.coop) | ⭕ | - | `@yusf:gottsnack.net` | Active  |
-| [eCommons](https://ecommons.nl) | ✅ | - | `@dannygroenewegen:matrix.org` | Active  |
-| [EOTL](https://eotl.supply) | ✅ | - | `@basebuilder:pub.solar` | Paused  |
-| [Karrot](https://karrot.world) | ⭕ | - | `@nicksellen:matrix.org` | Active  |
-| [Klasse & Methode](https://klasse-methode.it) | Waiver | - | `@p4u1_f4u1:matrix.org` | Active  |
-| [Kolektivo Sennacieca Cifereca](https://www.sekuro.nl) | ✅ | - | `@hex_m_hell:matrix.org` | Active |
-| [Local IT](https://local-it.org/)  | ✅ | - | `@simon_sth:matrix.org`| Active  |
-| [Merri-bek tech](https://www.merri-bek.tech/) | ✅ | - | `@sarah@merri-bek.tech`| Active  |
-| [MIR](https://mirnet.org/) | ✅ | - | `@sixsmith:matrix.org` | Active  |
-| [Red Abya Yala](https://abyayala.sutty.nl/) | ⭕ | - | `@fauno:sutty.nl` | Active  |
-| [RTM](https://resisttechmonopolies.online) | ✅ | - | `@ammaratef45:matrix.org`| Active  |
-| [ruangrupa](https://ruangrupa.id) | ⭕ | - | `@babystepper:matrix.org` | Paused  |
-| [UTAW](https://utaw.tech) | ⭕  | - | `@javielico:matrix.org` | Paused  |
-| Amras | Waiver | - | `coop-cloud@joinmeonmy.quest` | Active  |
-| Mirsal ™  | ✅ | - | `@mirsal:1312.media` | Active  |
+| Name      | Dues Paid | Notes    | Contact |
+| --------- | --------- | -------- |-------- |
+| [Agaric](https://agaric.coop/) | ⭕ | - | `@wolcen:matrix.org` |
+| [Autonomic](https://autonomic.zone) | ⭕ | - | `@3wc`, `@cas`, `@knoflook`, `@travvy`, `@aadil` |
+| [Bonfire](https://bonfirenetworks.org) | ✅ | - | `@mayel:matrix.org` + Ivan (`@cambriale:matrix.org`) |
+| [Bunk Computer Cooperative](https://bunk.computer) | ✅ | - | `@maren@bunk.computer` + `@sorrel@bunk.computer` |
+| [CoQuest - IT Coop Stuttgart](https://coquest.coop/en) | ✅ | voting rights waived | `hallo@coquest.coop` |
+| [Democratic Tech Fund](https://democratictech.fund/) | ✅ | - | `@wtebbens` + `@mikemh` |
+| [Doop.coop](https://doop.coop) | ⭕ | - | `@yusf:gottsnack.net` |
+| [eCommons](https://ecommons.nl) | ✅ | - | `@dannygroenewegen:matrix.org` |
+| [EOTL](https://eotl.supply) | ✅ | - | `@basebuilder:pub.solar` |
+| [Karrot](https://karrot.world) | ⭕ | - | `@nicksellen:matrix.org` |
+| [Klasse & Methode](https://klasse-methode.it) | Waiver | - | `@p4u1_f4u1:matrix.org` |
+| [Local IT](https://local-it.org/)  | ✅ | - | `@moritz:matrix.local-it.org` + `@simon_sth:matrix.org`|
+| [Merri-bek tech](https://www.merri-bek.tech/) | ✅ | - | `coop-cloud-delegate@merri-bek.tech`|
+| [MIR](https://mirnet.org/) | ✅ | - | `@sixsmith:matrix.org` |
+| [Red Abya Yala](https://abyayala.sutty.nl/) | ⭕ | - | `@fauno:sutty.nl` |
+| [RTM](https://resisttechmonopolies.online) | ✅ | - | `@ammaratef45:matrix.org` + `@linnealovespie:matrix.org`|
+| [ruangrupa](https://ruangrupa.id) | ⭕ | - | Henry `@babystepper:matrix.org` |
+| [UTAW](https://utaw.tech) | ⭕  | - | `@javielico:matrix.org` |
+| Amras | Waiver | - | `coop-cloud@joinmeonmy.quest` |
+| `@decentral1se` | Waiver | - | `@decentral1se` |
+| Mirsal ™  | ✅ | - | `@mirsal:1312.media` |

@@ -0,0 +1,24 @@
+---
+title: Organisers
+---
+
+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.
+
+<div class="grid cards" markdown>
+
+- __Organisers Handbook__
+
+    One-stop shop for all you need to know to organise in the community :sparkles:
+
+    [Read Handbook](/federation/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](/intro/contact/){ .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:
+
@@ -1,5 +1,5 @@
 ---
-title: CCF
+title: The Co-op Cloud Federation Proposal
 ---

 # The Co-op Cloud Federation Proposal
@@ -20,7 +20,7 @@ If this is the first time you're seeing the project, please do take a look at [c

 ## Overview

-As part of the [beta bikemap goals](/intro/bikemap) we are aiming to formalise the idea of what ["Co-op Cloud 'The Organisation'"](https://pad.autonomic.zone/s/C3uuqfSCk#Co-op-Cloud-%E2%80%9CThe-Organisation%E2%80%9D) could mean concretely. Here is what we wrote in our bike map originally:
+As part of the [beta bikemap goals](https://pad.autonomic.zone/s/C3uuqfSCk) we are aiming to formalise the idea of what ["Co-op Cloud 'The Organisation'"](https://pad.autonomic.zone/s/C3uuqfSCk#Co-op-Cloud-%E2%80%9CThe-Organisation%E2%80%9D) could mean concretely. Here is what we wrote in our bike map originally:

 > One of the core goals of Co-op Cloud is to have the project run and managed by a diverse group of tech co-ops and collectives who are invested into building, maintaining and extending this digital configuraton commons. In order to open the project up we need to work on shared governance guidelines, codes of conduct, building community trust and working towards economic sustainability.

@@ -1,18 +0,0 @@
---
-title: "Resolution 046: 3wc to join the federation as an individual member"
---
-
- Topic: Resolution 046: 3wc to join the federation as an individual member
- Date: 2026-09-30
- Deadline: 2026-10-15
- Size: large
-
-## Summary
-
-3wc to join the federation as an individual member
-
-## Details
-
-@3wc:autonomic.zone is an active member of our community and supports with some of the ongoing work. they were a member of one of our cooperative members (autonomic) but they are no longer part of the cooperative but would like to stay in the cooperative as an individual member.
-
-@ammaratef45:matrix.org from [RTM](https://resisttechmonopolies.online/) is happy to vouch.
@@ -1,37 +0,0 @@
---
-title: "Resolution 049: Budget 018: Backpay for Rapid Website Fixes"
---
-
- Topic: Budget 018: Backpay for Rapid Website Fixes"
- Date: 2026-11-02
- Deadline: 2026-11-16
- Size: Medium
-
-## Description
-
-### Context
-
-Last week, there was a push to quickly update the website at [coopcloud.tech](https://coopcloud.tech). A lot of information on the front page was out of date, and there were long-standing concerns that people who looked at the website couldn't find relevant information. There is a grant proposal deadline coming up at NLnet on Nov 3rd, where we will be applying for further toolshed development; it was important to correct the front page before then.
-
-### Work Performed
-
-*amras* performed 9 hours of work to
-
- restructure the frontpage
- write copy for the frontpage and several landing pages describing the community, toolshed, and hosting providers
- fix the layout of the page, which previously did not render well on mobile devices
-
-*d1* also worked on editing and writing for the new copy, but they have waived compensation for this work.
-
-The new structure was motivated by ideas from [R035](https://docs.coopcloud.tech/federation/resolutions/passed/035/) and discussions within the coop cloud matrix space. However, this work is **not** directly related to R035. The work did not modify the [new-website](https://git.coopcloud.tech/toolshed/new-website-jekyll-theme/) being developed by Sutty, only [the previously existing website](https://git.coopcloud.tech/toolshed/coopcloud.tech/).
-
-### Reason for Backpay
-
-Since the website changes needed to be pushed ahead of the nov 3rd deadline, we did not have time to propose/vote on the budget ahead of time.
-
-## Budget
-
-**Budget amount**: 180€ from the Federation's budget
-**When will the money be spent**: Immediately
-**Who will claim**: Amras Ciaszczyk
-**What is the money for**: 9 hours of backpay for website development
@@ -1,28 +0,0 @@
---
-title: "Resolution 047: Kolektivo Sennacieca Cifereca to join the federation as a member"
---
-
- Topic: Resolution 047: Kolektivo Sennacieca Cifereca to join the federation as a member
- Date: 2026-10-06
- Deadline: 2026-10-20
- Size: large
-
-## Summary
-
-[Kolektivo Sennacieca Cifereca](https://www.sekuro.nl) is a security and organizational consultancy responsible for the proof of concept  [Hestia](https://git.coopcloud.tech/hex/hestia) build quality and security analyzer and [CCSATool](https://git.coopcloud.tech/hex/CCSATool) security advisory tool. KSC is focused on the improving the security of the platform. 
-
-## Details
-
-At Kolektivo Sennacieca Cifereca we provide security consulting, security reviews, security program guidance, and penetration testing services. We would like to use and recommend services provided by Co-op Cloud member organizations, and thus have a vested interest in driving security improvements within the federation.
-
-We have worked closely with eCommons, providing security guidance and identifying opportunities for improvement at the federation level (recipe scanning via Hestia, and security advisory announcement via CCSATool).
-
-We agree with eCommon's assessment:
-
-> Co-op Cloud's federated model, tooling maintained collectively by the co-ops that use it, matches how we think infrastructure should be built and sustained. 
-
-Further, we believe that distributed systems may present additional challenges related to pushing forward security initiatives, but they provide increased resilience against state-level threat actors with the goal of shutting down infrastructure by geographical region or ideological alignment. 
-
-@dannygroenewegen:matrix.org from eCommons has agreed to vouch for this organization. 
-
-Kolektivo Sennacieca Cifereca's representative to the federation will be hex. He can be reached at `@hex:matrix.org` on Matrix or `biz@sekuro.nl` by email.
@@ -1,33 +0,0 @@
---
-title: "Resolution 048: Restore servers.coop as a Coop Cloud project"
---
-
- Topic: Restore servers.coop as a Coop Cloud project
- Date: 2026-10-13
- Deadline: 2026-10-27
- Size: medium
-
-### History
-
-[servers.coop](https://servers.coop) was launched as a project of Coop Cloud, intended to cooperatise lower down the stack than the abra toolshed. Similarly to how abra gives small cooperatives the tools to easily and collaboratively deploy services on a cloud, servers.coop is meant to support small cooperatives in deploying VPSs on hardware owned or managed by them.
-
-The project was left on the backburner for some years. Recently, we were motivated by rising data center costs and concerns about digital sovereignty to start working on the project again. A working group of four-ish people from the Coop Cloud community is currently working on defining and deploying an MVP.
-
-Servers.coop goals are closely aligned with those of Coop Cloud as a whole, but its usecases and userbase may end up diverging from those of abra. In the long term, servers.coop ought to become an independent collective, with its own governance, membership, budget, and infrastructure - similarly to how Coop Cloud grew from an Autonomic project into a distinct federation. In the short term, servers.coop needs the support of the Coop Cloud federation.
-
-### Proposal
-
-Formally, we treat servers.coop as a project of the Coop cloud federation.
-
-This grants the servers.coop project access to Coop Cloud's resources. For instance:
-
- Coop Cloud server infrastructure can be used to organize and manage the project, including:
-   - conferencing or notetaking services provided by members for Coop Cloud use
-   - git.coopcloud.tech
-   - build.coopcloud.tech
-   - the servers.coop domain and subdomains
- Grants written on behalf of Coop Cloud can include servers.coop in their goals and budget.
- Coop Cloud federation members can propose and vote on resolutions regarding servers.coop governance, infrastructure, and budget.
- Coop Cloud budget can be allocated to servers.coop goals, through resolutions.
-
-This support is intended to be temporary. Over the course of several years, the group working on/with servers.coop ought to move its resources onto dedicated instances and establish its own structure of governance and financing. When this happens, a new resolution should be passed to formally establish the new collective and change how Coop Cloud participates in the project.
@@ -1,3 +0,0 @@
---
-title: Surveys
---
@@ -1,12 +0,0 @@
---
-title: Usage Survey (2026)
---
-
-Federation member `@hex` conducted our first community usage survey in October 2026.
-
-> [...] In the end we had 62% coming from Europe, 31% from North America, 1 from Austrailia, and 1 from South America. 
-85% responded that they maintain recipes, 77% manage services for customers. Almost half added more information on their use cases. 
-The majority of respondents were "small" organizations. 69% were managing services for themselves or for less than 10 customers, while about 1/3 were what might be described as "medium to large" organizations (with 101-1000 customer organizations). I think this presents a really interesting picture of the Federation, with a diverse ecosystems from tiny to large organizations all interacting and cooperating.
-
-Here is a link to all the results: [`results.csv`](/results.csv). Please note,
-all identifying information has been stripped out.
@@ -0,0 +1,12 @@
+---
+title: Digital tools
+---
+
+- [Public documentation](https://docs.coopcloud.tech/federation)
+- [Git hosting](https://git.coopcloud.tech/)
+- [Matrix Space](https://matrix.to/#/#coop-cloud-space:autonomic.zone)
+- [Website](https://coopcloud.tech/)
+- [Single Sign On](https://translate.coopcloud.tech/)
+- [Translation](https://translate.coopcloud.tech/)
+- [Sheets and time tracking](https://sheets.coopcloud.tech/)
+- [Drone CI/CD](https://build.coopcloud.tech)
@@ -1,3 +0,0 @@
---
-title: Digital Tools
---
@@ -2,94 +2,8 @@
 title: Bike map
 ---

-# Project Status
-
 - The project is currently in a [beta quality](https://en.wikipedia.org/wiki/Software_release_life_cycle#Beta) release state.

 - We are working towards a stable `1.0.0` release.

 - What we're currently working on is listed on this issue tracker: [`toolshed/projects`](https://git.coopcloud.tech/toolshed/-/projects).
-
-## Co-op Cloud beta bikemap
-
-!!! note
-
-    The bikemap below has not been updated for a while and should probably be updated to reflect the current status.
-
-![](https://vvvvvvaria.org/~decentral1se/cc/fietsen.jpg)
-
-> We're not very fond of the word "roadmap" which is the word traditionally used to mean something like "a list of goals to achieve in a given time" :stuck_out_tongue: The following are not listed in any particular order of priority and are subject to change. We are using [these milestones](https://git.coopcloud.tech/coop-cloud/organising/milestones) to track our work on this bike map. We also have this [Project board](https://git.coopcloud.tech/coop-cloud/organising/projects/8) for coordinating our weekly work.
-
-### Command-line tool sustainability
-
-The pre-alpha/alpha command-line tool for managing a Co-op Cloud instance (e.g. [`abra`](https://git.coopcloud.tech/coop-cloud/abra-bash)) is written in [Bash](https://www.gnu.org/software/bash/). This choice was made because we had little to no funding, no clear idea of a final design and were very much in experimentation mode. This choice served us well but we began to run into the limitations of this approach - difficulty in parsing different file formats, concurrent programming and command-line input handling.
-
-As part of the Beta release, we have decided to reimplement and extend `abra` in the [Go programming language](https://golang.org/) as it overcomes the limitations listed above and significantly improves our ability to deliver a cross-platform portable command-line tool without much fuss. We're fans of the [Dokku project](https://dokku.com) which also took [a similar approach](https://github.com/dokku/dokku/discussions/4258#discussioncomment-289670).
-
-### Versioning and deploy stability
-
-We want to make deploying libre apps simple and reliable.
-
-This means putting work into the `abra` command-line interface and making sure `abra` understands what the container runtime is telling it (did the deployment succeed, fail, needs a rollback, etc.) and reporting clearly what is happening on the command-line.
-
-We also need to know which versions of which libre apps are available. And more importantly, which are reliable and can be deployed safely with some assurances that they will work? This involves coordinating with upstream publishing rhythms and integrating with a test suite (see below for more).
-
-### Continuous integration testing for apps
-
-Libre app developer communities are publishing new versions of their apps all the time. However, not all versions deploy succesfully due to changes in configuration and/or bugs in the software. When this happens, we need to do some packaging work on the Co-op Cloud side to ensure things work.
-
-In order to understand when a new version requires some work before it can become available for deploying, we need to implement a test suite which will put the new version through a series of tests to ensure it works.
-
-### Backup and restore
-
-After you deploy your app, you need to take care of it. That means backing it up and sometimes, restoring it (e.g. if you move to another server). Another case is when an upgrade fails and you want to restore to a previous version safely. We want to provide a simple way to backup/restore apps through `abra`.
-
-### Co-op Cloud "The Organisation"
-
-One of the core goals of Co-op Cloud is to have the project run and managed by a diverse group of tech co-ops and collectives who are invested into building, maintaining and extending this digital configuraton commons.
-
-In order to open the project up we need to work on shared governance guidelines, codes of conduct, building community trust and working towards economic sustainability.
-
-### Compensating contributors
-
-People should be compensated for the work they contribute to Co-op Cloud. This work could mean packaging new apps, fixing the tools we build, writing blog posts, giving work shops, doing user support and so on.
-
-We need to self-organise a clear process to help people understand how to get compensated for their work and in relation to other types of work. And this must be done in a sustainable way.
-
-### Wider libre apps selection
-
-We want to have more libre apps available for end-users. We currently have over 60+ apps available but there are many more which cover different needs. This catalogue should be simple to navigate and understand what apps are available and what those apps are for.
-
-### Payments and billing
-
-Too often, open source platforms leave the financial work to out-of-band organisational processes or altogether ignore the need, relying on unsustainable maintenance practices.
-
-Functionality and design for accepting payments from end-users and handling the administration of billing for hosters is critical to support financial sustainability of Co-op Cloud instances.
-
-### Documentation
-
-Clear, concise and simple documentation designed for multiple publics (tech co-ops, end-users, general public) is an incredibly important goal for our Beta release. Quality documentation helps build capacity, understanding and promotes knowledge sharing across the project. In this sense, the documentation may be more important than the source code.
-
-### UI / UX testing
-
-Intensive user interface and experience testing will take place across different user groups and with different focuses in order to discover what we're getting right, what we're getting wrong and how to prioritise development of the project.
-
-### Portability testing (software/hardware)
-
-Modern computing takes place on many different architectures, hardware and in diverse conditions with regard to networking and power requirements. We want the Co-op Cloud to be performant, run reliably and be portable to support different needs. This means deploying and testing Co-op Cloud instances in different environments.
-
-### Cloud provisioning portability (Hetzner, DO, Linode, etc.)
-
-Co-op Cloud should support running on different cloud environments and support 3rd party integrations with VPS and DNS providers. We are especially interested in supporting integrations with tech co-op providers such as [servers.coop](https://servers.coop). This kind of automation is expected when using corporate providers and we want to achieve this level of convenience as well.
-
-### Pen Testing/security
-
-Security is important and we want to provide a realistic guarantee of what Co-op Cloud can and cannot offer. This means working with security communities in order to analyse how secure our system is.
-
-### Design and aesthetics
-
-We want to develop and maintain a visual aesthetic and design presence which communicates what the project is about and the values it promotes.
-
-### Public communications
-
-We want to have clear guidelines and processes around how we communicate the project to a wide public and how to self-organise that inside the project.
@@ -10,9 +10,9 @@ The urgency to build an alternative to ["corporate clouds"](https://2023.transme

 We begin with the monopolisation of our digital lives, the stranglehold of corporate control (aka [GAFAM](https://degooglisons-internet.org/en/)), which represents a grave threat to our collective freedom, our societies and our hopes for a good life on planet earth.

-We acknowledge the vast accumulation of network effects and resources accrued by these monopolies. This is the basis of our understanding that no single project, "product" or organisation can create the required shift to a more widespread democratic technology.
+We acknowledge the vast accumulation of network effects and resources accrued by these monopolies. This is the basis of our understanding that no single project, "product" or organisation can create the required shift to a more widespread public interest technology.

-When we say democratic technology, we mean a technology which is not built in the service of monopoly. We are speaking of a technology which emerges from elements of democracy: bottom-up decision making, social need, community ownership and ecological thinking. Our aspiration is a technology which is built in the service of social justice, equality and collective freedom.
+When we say public interest technology, we mean a technology which is not built in the service of monopoly. We are speaking of a technology which emerges from elements of democracy: bottom-up decision making, social need, community ownership and ecological thinking. Our aspiration is a technology which is built in the service of social justice, equality and collective freedom.

 Our strategy is to mutualise our resources to facilitate this shift. We harbour no illusions: technology alone will not "save us" and simply deploying libre software is not enough. We do not operate in a bubble and do not wish to remain contained within a subculture.

@@ -264,6 +264,10 @@ At time of writing (Jan 2022), we think there is a limitation in our design whic

 This may be possible to overcome if someone really needs it, we encourage people to investigate. We've found that often there are limitations in the actual software which don't support this anyway and several of the current operators simply use a new domain per app.

+## Can I add worker nodes to my docker swarm?
+
+At time of writing (Sep 2026), we officially only support single-node swarms. However, we are working on improving our tools and understanding to support multi-node in the future. If you'd like to get involved, [here is what we know so far](/operators/multinode).
+
 ## How do I bootstrap a server for running Co-op Cloud apps?

 The requirements are:
@@ -0,0 +1,272 @@
+---
+title:  Multinode Best Practices
+---
+
+## Who This How-To Guide is For
+
+Configuring coop cloud on multiple nodes poses some difficult problems, and we have not yet streamlined this process. For the sake of security and sanity, you should have a good understanding of the following before you attempt this:
+
+- VPN configuration, understanding how authentication and encryption are handled.
+- Firewalls, and `iptables` in particular.
+- Managing and synchronizing files on a network (e.g. sftp, nfs, rsync)
+
+What follows is our best knowledge to date. Tread carefully, for here be dragons.
+
+## Before You Start
+
+**1. *On every node*, make sure docker is installed and running.
+
+```bash
+docker run hello-world
+```
+
+**2. *On every node*, ensure kernel modules `ip_vs`[^ip_vs] and `br_netfilter`[^br_netfilter] are loaded.
+
+```bash
+lsmod | grep -E "^ip_vs |^br_netfilter "
+```
+
+??? Why?
+    
+    - `ip_vs` enables multiple Linux kernels to act as *one* virtual server, coordinating request handling and processing with eachother over IP. [kernelconfig.io](https://www.kernelconfig.io/config_ip_vs)  
+    - `br_netfilter` enables the kernelspace netfilter capability for bridge network interfaces. Without this kernel module, docker needs to route swarm packets via a slow and insecure userland proxy to communicate with the other docker networks. [Serverfault answer](https://serverfault.com/a/964491), [kernelconfig.io](https://www.kernelconfig.io/CONFIG_BRIDGE_NETFILTER?q=br_netfilter&kernelversion=7.2.4&arch=x86)
+
+**3. Choose one node to be the manager node.
+
+Ensure you can connect to this node with `ssh`.
+
+!!! info "If your server isn't reachable"
+
+    If your manager node is not your main traefik proxy, `abra` may complain about the server not being reachable from the Internet. You can use the `-D` flag to ignore this warning.
+
+??? warning "Do you need multiple manager nodes?"
+
+    It's easiest to start your setup by choosing only one node in your swarm to be the manager (the others will be worker nodes). If you need multiple manager nodes, e.g. to improve uptime, [read this first](https://docs.docker.com/engine/swarm/how-swarm-mode-works/nodes/#manager-nodes).
+
+**4. establish a trusted network connection between each worker node and the manager.
+
+This can be
+
+- A standard "hub-and-spokes" VPN like strongswan, where worker nodes are connected to the manager node,
+- Or a mesh VPN like tailscale, where all nodes are connected together.
+
+??? info "Use a route-based VPN"
+
+    There are two types of VPN implementations: policy-based and route-based. They differ in that route-based VPNs create a distinct network interface for trusted traffic. We'll be using this interface in the next step.
+
+**5. *On every node*, using `iptables`[^iptables], block ingress on ports `2377/tcp`, `4789/udp`, `7946/udp`, `7946/tcp` except when it comes from a trusted interface. [Docker docs](https://docs.docker.com/engine/swarm/swarm-tutorial/#open-protocols-and-ports-between-the-hosts).
+
+E.g., if trusted packets arrive on `vpn0`:
+
+```bash
+iptables -A INPUT -p tcp --dport 2377 -i !vpn0 -j DROP
+iptables -A INPUT -p udp --dport 4789 -i !vpn0 -j DROP
+iptables -A INPUT -p udp --dport 7946 -i !vpn0 -j DROP
+iptables -A INPUT -p tcp --dport 7946 -i !vpn0 -j DROP
+```
+
+??? warning "Use iptables, not nftables"
+
+    All hosts must use `iptables` as the firewall backend, not `nftables`. Nftables support in Docker is experimental, and docker swarm mode hasn't been migrated to support nftables yet. [docker docs](https://docs.docker.com/engine/network/firewall-nftables).
+    
+## Configuring the Swarm and Abra
+
+**1. In `abra`, create a server using the manager node. (Refer to the [New Operators' Tutorial](https://docs.coopcloud.tech/operators/tutorial/) for a refresher on how to do this.)
+
+When calling `docker swarm init`, include `--advertise-addr` and point to the trusted interface of your VPN.
+
+**2. On the *manager node*, call
+
+```bash
+docker swarm join-token worker
+```
+
+**3. On a *worker node*, call the command provided, e.g.
+
+```bash
+docker swarm join --token MYTOKEN M.Y.I.P:2377
+```
+
+**4. On the *manager node*, verify the node is in the swarm:
+
+```bash
+docker node ls
+```
+
+## Volume Duplication
+
+!!! warning "Docker swarm does not synchronize volume data between nodes."
+
+    - If services on the same recipe deploy on different nodes, they will not have access to any volumes shared between them.
+    - If a service dies or is stopped, and docker swarm deploys it to a different node, it will not have access to its existing volume data.
+
+You must choose one of these strategies:
+
+**1. Using placement constraints, restrict apps to always run on specific nodes.
+
+**2. Choose a networked filesystem (e.g. nfs, rclone) and use its *docker volume plugin* to synchronize volume data between worker nodes.
+
+Both strategies are described below.
+
+### How to restrict apps to specific nodes
+
+**1. In your *abra config*, create a new compose file and set appropriate deploy.placement.constraints for each service. For example:
+
+`~/.abra/compose/compose.restrict-nextcloud.yml`
+
+```yml
+---
+version: "3.8"
+
+services:
+  web:
+    deploy:
+      placement:
+        constraints:
+          - node.labels.nextcloud_node == true
+  app:
+    deploy:
+      placement:
+        constraints:
+          - node.labels.nextcloud_node == true
+  cron:
+    deploy:
+      placement:
+        constraints:
+          - node.labels.nextcloud_node == true
+  cache:
+    deploy:
+      placement:
+        constraints:
+          - node.labels.redis_node == true
+          # nb: redis does not share volumes with other services,
+          # so it could be deployed on a separate node.
+```
+
+**2. On your *worker node*, assign the appropriate labels:
+
+```bash
+docker node update --label-add nextcloud_node=true --label-add redis_node=true <worker_hostname>
+```
+
+**3. On the *abra server*, Add your compose file to your app's config. E.g.:
+
+```bash
+abra app config my.app
+```
+
+```yml
+...
+COMPOSE_FILE="compose.yml"
+COMPOSE_FILE="$COMPOSE_FILE:../../compose/compose.restrict-nextcloud.yml"
+...
+```
+
+**4. Deploy the app.
+
+**5. Confirm all the services were correctly assigned:
+
+```bash
+docker node ps <worker_hostname> | grep "Running"
+```
+
+??? info "You can make much more complex setups with placement constraints and node configurations"
+
+    - [Placement constraints (about)](https://docs.docker.com/engine/swarm/services/#control-service-placement)
+    - [Placement constraints (compose file reference)](https://docs.docker.com/reference/compose-file/deploy/#placement)
+    - [Node labels (how to)](https://docs.docker.com/engine/swarm/manage-nodes/#add-or-remove-label-metadata)
+
+### How to Use docker volume plugins
+
+!!! warning "Do not use this strategy to synchronize database volumes."
+
+    Instead:
+        - optionally configure a distributed database across your nodes (unknown what tools are best).
+        - be careful when using `db` services in your recipes. Ignore them in favor of a dedicated database instance, or restrict the services to a dedicated node.
+        - in your app configuration, use `DB_HOST` and similar environment variables to point to your network's database host.
+
+!!! warning "Use the S3 protocol wherever a recipe allows it."
+
+    S3 is much more efficient at synchronizing large amounts of data. We recommend [garage](https://git.coopcloud.tech/coop-cloud/garage).
+    On the other hand, avoid using `s3fs` to store docker volumes - this can cause race conditions because S3 does not allow file locking.
+
+**1. Choose a machine to be your dedicated volume data store.
+
+**2. On your *data storage machine*, choose and install a network-accessible file store. Just about anything can be made to work (with tradeoffs): ssh, nfs, NextCloud, WebDav, ProtonDrive, etc.
+
+**3. Ensure your file store can be securely accessed from every worker node.
+
+**4. *On every node in your swarm*, install a dedicated docker volume plugin for your file store, or use a generic middleware like [Rclone](https://rclone.org/docker/).
+
+**5. In your *abra config*, create a custom compose file and configure the plugin on all of your recipe's volumes. E.g.:
+
+`~/.abra/compose/compose.nextcloud-rclone.yml`
+
+```yml
+---
+version: "3.8"
+
+volumes:
+  nextcloud:
+    driver: rclone
+    driver_opts:
+        ...
+  nextapps:
+    driver: rclone
+    driver_opts:
+        ...
+  nextdata: # note: you should use S3 for the majority of your data.
+    driver: rclone
+    driver_opts:
+        ...
+  nextconfig:
+    driver: rclone
+    driver_opts:
+        ...
+ # here we skip the redis volume, because its cache data
+ # doesn't need to be persisted between nodes
+```
+
+**6. Include the compose file in your instance's config. E.g.
+
+```bash
+abra app config my.app
+```
+
+```yml
+...
+COMPOSE_FILE="compose.yml"
+COMPOSE_FILE="$COMPOSE_FILE:../../compose/compose.nextcloud-rclone.yml"
+...
+```
+
+**7. Deploy the app
+
+**8. Optionally, verify the volumes are no longer on disk:
+
+```bash
+docker volume ls
+sudo ls /var/lib/docker/volumes/
+```
+
+**9. Optionally, destroy any volumes that were previously created:
+
+```bash
+docker volume prune -a
+```
+
+## Additional Notes
+
+- Manager nodes should be placed on your most reliable machines, since without them workers cannot deploy services. Because of this, you may want to constrain critical apps to run only on managers: `node.role == manager`.
+- If an app needs certain resources to be available (e.g. 4 GiB RAM), you can set a resource constraint, which ensures the app can only be scheduled on nodes with that resource available. [See docker docs](https://docs.docker.com/reference/compose-file/deploy/#resources)
+- A Docker swarm cluster should have an odd number of manager nodes. 1 manager is sufficient, and 3 managers is the minimum for redundancy. [See docker docs](https://docs.docker.com/engine/swarm/how-swarm-mode-works/nodes/#manager-nodes)
+- When using a swarm with worker nodes, some information will be invisible to abra. In particular, `abra app logs` and `abra app ps` will (at time of writing) give incomplete information. Here are some workarounds:
+    - Instead of `abra app logs example.com app`, call `docker service logs example_com_app` on a manager node.
+    - In addition to `abra app ps example.com`, try: `docker node ps <node_name> | grep example_com`, `docker service ps example_com_app`, `docker service ls -f name=example_com`, `docker stats`
+- Abra can only interact with manager nodes; worker nodes lack permissions to run most of abra's commands. When creating an `abra server`, remember to connect to a manager node.
+
+### Additional Resources
+
+- [nix-config by papiris](https://codeberg.org/papiris/nix-config/src/branch/main/overlays/virtualisation/docker.nix) (multi-node Co-op Cloud, docker within systemd-nspawn)
+- [SweHarris blog post](https://www.sweharris.org/post/2017-07-30-docker-placement/) about docker swarm placement
+- [OneUpTime article](https://oneuptime.com/blog/post/2026-03-20-portainer-service-placement-constraints/view) by @nawazdhandala about docker swarm placement
@@ -1,8 +1,3 @@
 ---
 title: Specifications
 ---
-
-We gather all community written specifications here. Specifications are useful
-for coordinating implementation across moving parts and different tools which
-everyone needs to understand. One clear example is how `backup-bot-two` and
-`abra` interact.
@@ -9,6 +9,7 @@ theme:
  features:
      navigation.instant.progress
    - content.action.edit
+    - navigation.expand
    - navigation.indexes
    - navigation.instant
    - navigation.path
@@ -79,18 +80,25 @@ nav:
      - "Packaging Handbook": maintainers/handbook.md
      - maintainers/catalogue.md
  - "Operators":
+      - operators/index.md
      - "New operators Tutorial": operators/tutorial.md
      - "Operators Handbook": operators/handbook.md      
  - "Federation":
      - federation/index.md
+      - federation/handbook.md
+      - federation/organisers.md
+      - federation/kite-flying-pad-archive.md
      - "Bylaws": federation/bylaws.md
      - "Finance": federation/finance.md
      - "Membership": federation/membership.md
-      - "Join the CCF": federation/join.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":
+        - federation/proposals/index.md
        - federation/proposals/federation.md
      - "Resolutions":
+          - federation/resolutions/index.md
          - "Draft":
              - federation/resolutions/index.md
          - "Passed":
@@ -136,18 +144,16 @@ nav:
              - federation/resolutions/passed/042.md
              - federation/resolutions/passed/043.md
              - federation/resolutions/passed/044.md
-              - federation/resolutions/passed/047.md
          - "Stalled":
              - federation/resolutions/stalled/013.md
              - federation/resolutions/stalled/030.md
          - "In Progress":
              - federation/resolutions/in-progress/045.md
-              - federation/resolutions/in-progress/046.md
              - federation/resolutions/index.md
      - "Minutes":
+          - federation/minutes/index.md
          - "Recently":
              - federation/minutes/2025-12-28.md
-              - federation/minutes/kf-archive.md
          - "Archive":
              - federation/minutes/2024-08-15.md
              - federation/minutes/2024-04-17.md
@@ -155,19 +161,14 @@ nav:
              - federation/minutes/2024-02-01.md
              - federation/minutes/2022-03-03.md
              - federation/minutes/2023-05-03.md
-      - "Digital Tools":
-          - federation/tools/infra.md
-      - "Surveys":
-          - federation/surveys/usage-2026.md
+      - "Digital Tools": federation/tools.md
      - "Funding applications":
-          - federation/funding/culture-of-solidarity.md
-          - federation/funding/ford-foundation.md
-          - federation/funding/private-funder.md
-          - federation/funding/sovereign-tech-fund.md
-          - federation/funding/user-operated-internet.md
-          - federation/funding/sovereign-tech-fund.md
-          - federation/funding/nlnet-codesupply.md
-          - federation/funding/nlnet-restack.md
+          - federation/funding-applications/index.md
+          - federation/funding-applications/culture-of-solidarity.md
+          - federation/funding-applications/ford-foundation.md
+          - federation/funding-applications/private-funder.md
+          - federation/funding-applications/sovereign-tech-fund.md
+          - federation/funding-applications/user-operated-internet.md
  - "Abra":
      - abra/index.md
      - "Install": abra/install.md
@@ -182,6 +183,7 @@ nav:
  - "Specifications":
      - specs/index.md
      - "Backups":
+          - specs/backup/index.md
          - specs/backup/maintain.md
          - specs/backup/spec.md