added some details for offline coopcloud

It took me some time to figure out how to set up the server with abra, the right host names, and the wildcard-cert so I thought these info might help others to set up an offline coopcloud more easily.

docs/abra/hack.md

@@ -99,6 +99,53 @@ The drone configuration was wired up as follows:
 
 Please ask `@decentral1se` or on the Matrix channels for SSH access to the machine.
 
+### Running manually on the CI server
+
+It's convenient to be able reproduce the CI server environment yourself by SSHing to the machine and running the integration tests. Here's how you do it.
+
+SSH config details:
+
+```
+Host int.coopcloud.tech
+  Hostname 51.159.168.99
+  User root
+  Port 22
+  IdentityFile ~/.ssh/<private-key-part>
+```
+
+Once you're in, you can run the following:
+
+```
+sudo -su abra
+cd
+tmux ls # if there is a session, run: tmux attach
+        # this way, we don't crash into each other
+        # when we're running tests
+./run-ci-int
+```
+
+You can also `cd abra` and run `bats ...` directly to trigger specific subsets
+of tests. You'll need to export the env vars at the bottom of the `run-ci-int`
+script to reproduce the same settings.
+
+```
+export ABRA_DIR="$HOME/.abra_test"
+export TERM=xterm
+export TEST_SERVER=default
+export ABRA_CI=1
+```
+
+And then ensuring a clean state and running with the same flags:
+
+```
+rm -rf "$ABRA_DIR"
+bats -Tp tests/integration --filter-tags \!dns --print-output-on-failure
+```
+
+See the [`run-ci-int`](https://git.coopcloud.tech/toolshed/abra/src/branch/main/scripts/tests/run-ci-int) script for more.
+
+See below for more tips on how to run the tests.
+
 ### Running them locally
 
 #### Install dependencies
@@ -380,11 +427,7 @@ The project with all changes and discussions is [here](XXX).
 
 A huge thanks to all our `abra` hackers for this release 💖
 
-```
-...
-```
-
-$CHANGELOG
+$git_shortlog_output
 ```
 
 #### General announcement text
@@ -416,6 +459,10 @@ Happy Hacking 🫂
 
 We maintain a fork of [godotenv](https://git.coopcloud.tech/toolshed/godotenv) because we need inline comment parsing for environment files. You can upgrade the version here by running `go get git.coopcloud.tech/toolshed/godotenv@0<COMMID>` where `<commit>` is the latest commit you want to pin to. See [`abra#391`](https://git.coopcloud.tech/toolshed/abra/pulls/391) for more.
 
+### `docker/cli`
+
+We maintain a fork of [docker-cli](https://git.coopcloud.tech/toolshed/docker-cli/) because we needed to [patch port exposing](https://git.coopcloud.tech/toolshed/docker-cli/commit/2fbb22f65866ac97b47e4d47d8f855fee8c98e2a) to fix this [bug](https://github.com/docker/cli/issues/2407). Once the [fix was upstreamed](https://github.com/docker/cli/pull/6799) we can remove this fork again. 
+
 ### `docker/client`
 
 A number of modules in [pkg/upstream](https://git.coopcloud.tech/toolshed/abra/src/branch/main/pkg/upstream) are copy/pasta'd from the upstream [docker/docker/client](https://pkg.go.dev/github.com/docker/docker/client). We had to do this because upstream are not exposing their API as public.

docs/abra/swarm.md

@@ -0,0 +1,55 @@
+---
+title: Swarm mode almanac
+---
+
+> !!! warning "This page is a Work In Progress :tm:"
+    A page to understand WTF is going on with [Swarm mode](https://docs.docker.com/engine/swarm/key-concepts/) and how we rely on it, how we might not rely on it and other related threads. Please add to this page as you see fit! If we can establish some shared understanding of what is going on under the hood, we can come up with a collective solution which meets everyones needs.
+
+## Support matrix
+
+In practice, this is what we currently rely on Swarm mode for.
+
+| Feature | Explanation |
+| ----------- | ----------- |
+| Encrypted secrets | When you run `abra secret generate`, it uses something like `printf foo | docker secret create foo -` under the hood. This feature only works if you have first run `docker swarm join`. Swarm mode [securely transports and stores your secret encrypted on the server](https://docs.docker.com/engine/swarm/secrets/#how-docker-manages-secrets). `docker compose` does not support encrypting or storing secrets because it only runs client-side. |
+| 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). |
+
+## Unsupport matrix
+
+| Feature | Explanation |
+| ----------- | ----------- |
+| Multi-node | It is possible but it doesn't seem like anyone in our community is really doing this. We believe 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 [the majority](https://docs.docker.com/engine/swarm/#feature-highlights) of the features of Swarm mode. |
+
+## Limitations
+
+* Swarm mode is still eerily underdeveloped and lacking features as a system. There are still some lurking network and stability bugs which are common. We're grateful for the undercover live reporting from people in-the-know adjacent to our network below. There are even folx inside Docker who are apparently calling it abandonware ([source](https://git.coopcloud.tech/toolshed/organising/issues/682#issuecomment-30235)). All this does not really put us at ease.
+
+!!! note "Docker whiskey leaks"
+
+    > https://www.mirantis.com/blog/mirantis-guarantees-long-term-support-for-swarm/
+    >
+    > Mirantis' relationship with "swarm" is very confusing! my understanding is that there are people (or one person? lol) at mirantis who do some work on the orchestration engine that is "docker swarm," but only to the extent that it supports mirantis' platform. i don't believe there's any active feature development beyond that. you're right that it's a misleading headline -- it sounds to me that they're just saying that they'll continue swarm support in their v3 kubernetes platform, not that they're committed to developing swarm as an orchestration system.
+    >
+    > Way back when (i guess in 2019? before my time!), docker sold off its enterprise platform which was called "swarm" to mirantis, so that's still a product that mirantis has and has developed in their way, but it's not the open-source swarm(kit) that's part of the docker cli. this is a good quick explanation: https://forums.docker.com/t/docker-swarmkit-and-the-mirantis-deal-not-docker-swarm/88886
+
+* The orchestration features of Swarm mode are opaque, causing failed deployments to be difficult to understand. This can cause a litany of a issues. For example, in the case where your database has been migrated and a rollback of your failing app doesn't support the new schema. This is being discussed extensively on [`organising#682`](https://git.coopcloud.tech/toolshed/organising/issues/682).
+
+## Potential alternatives
+
+* [`uncloud.run`](https://github.com/psviderski/uncloud): The Uncloud folks are creating a very different system. Something beyond compose but not k8s and not Swarm. This means they have to implement a lot of features of the orchestration from scratch. However, they're going for a nice approach: a straight-forward imperative deployment model (supports `depends_on` for predictable ordering during deployments). They're choosing which parts of the Compose Spec they implement and it's noteworthy that they [don't implement secrets yet](https://github.com/psviderski/uncloud/issues/75). See the [Compose support matrix](https://uncloud.run/docs/compose-file-reference/support-matrix) for more. They are however very focused on multi-node functionality. It's a system to [keep an eye on](https://github.com/psviderski/uncloud/milestone/1) with the hope that we can use some part of it in the future. Lines of communication [have been opened](https://github.com/psviderski/uncloud/discussions/255).
+
+* [`docker compose`](https://github.com/docker/compose): Plain old `docker compose`. A more elegant weapon for a more civilised age. It is however missing features we need such as encrypted secrets and `template_driver` support. There may be [more things missing](https://github.com/docker/compose/issues/11867). They are developing a promising [SDK](https://docs.docker.com/compose/compose-sdk/) exposes a public API for handling various operations. This would need some serious investigation and most likely some custom solutions for the features we're missing.
+
+## What we need
+
+* Something that is backwards compatible with our existing recipe configuration commons and the current deployments. We can't re-invent the wheel because we all rely on this system. So, we need to look towards incremental improvements or changes which are backwards compatible. We can always agree to change the config commons or some shared practices but then we need to establish a clear agreement with decision making. This is the social part.
+
+* Some way of conveniently using secrets when deploying services. This method should easily support working in a team which doesn't stray too far from our established Git Ops workflow of sharing `$ABRA_DIR`. They don't need to be encrypted and stored on the server (removing the need for Swarm mode handling) as long as they're mounted as secrets in the usual `/run/secret/<name>` manner at runtime.
+
+* Template driver support so we can template values into our configurations. This is used in enough recipes to warrant continued support.
+
+* A way to namespace services into a deployment, aka a "Docker Stack". This would appear to be a minor implementation detail after all is said and done. It's services all the way down and they have some linked networks/configs/volumes/etc. and a shared naming convention.
+
+* Some way to achieve [Fearless YunoHost-esque Upgrades](https://git.coopcloud.tech/toolshed/organising/issues/682#issuecomment-29302). In other words, some predictable way to deploy / upgrade / rollback and some way to intervene when things go wrong. It should be easy to understand for everyone and would enable real stability for operators. I think we want some sort of anti-orchestration implementation which is super simple.

docs/abra/trouble.md

@@ -105,4 +105,4 @@ $ git clone https://git.coopcloud.tech/coop-cloud/MyCoolRecipe.git ~/.abra/recip
 
 ## "only updates to Labels are allowed"
 
-See [Packaging handbook » What does "only updates to Labels are allowed" mean](maintainers/handbook/#what-does-only-updates-to-labels-are-allowed-mean).
+See [Packaging handbook » What does "only updates to Labels are allowed" mean](/maintainers/handbook/#what-does-only-updates-to-labels-are-allowed-mean).

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

@@ -0,0 +1,33 @@
+---
+title: "Resolution 035: Budget 016: Sutty Website Proposal"
+---
+
+- Topic: Budget 016: Sutty Website Proposal
+- Date: 2026-02-12
+- Deadline: 2026-02-26
+- Size: Large
+
+## Summary
+
+Budget 016 proposes to:
+
+1. Compensate Sutty and Co-op Cloud community members `@edu` & `@eli` 250 USD (500 USD total) each according to their own proposed compensation.
+1. Compensate `@diatom` for up to 30 hours to participate in the generative process as Co-op Cloud community delegate.
+
+Please see [the full proposal text](https://vvvvvvaria.org/~decentral1se/cc/CoopCloud-2025WebsiteProposal-Sutty.pdf) for more details. See `Capítulo 3 > Resources estimations` for the section regarding financial estimations. The Co-op Cloud community and federation are to be consulted during this process for decision making around choosing a new website proposal. `@diatom` agrees to be a bridge between the work of `@edu`/`@eli` and the Co-op Cloud community.
+
+## Details (Budget 016)
+
+This resolution follows the Good Work of `@sef`/`@edu`/`@eli` in carrying out the Co-op Cloud Community Website Survey. The idea is that `@edu` and `@eli` (with the blessing of `@sef`) will now bring forward a concrete proposal for the new Co-op Cloud website based on their proposed generative process. Please see [the full proposal text](https://vvvvvvaria.org/~decentral1se/cc/CoopCloud-2025WebsiteProposal-Sutty.pdf) for all details.
+
+#### Budget
+
+`@edu`/`@eli`/`@diatom` will carry out this work.
+
+Please join `#coop-cloud-new-website:autonomic.zone` to participate in this process. All community members are welcome.
+
+The budget total is:
+
+* 500 USD (423 EUR)
+* 30 hrs * 20 EUR = 600 EUR
+* **Total**: 1023 EUR

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

@@ -0,0 +1,26 @@
+---
+title: "Resolution 037: Adopt alakazam as an official project in the Co-op Cloud Federation"
+---
+
+- Topic: Resolution 037: Adopt alakazam as an official project in the Co-op Cloud Federation
+- Date: 12-02-2026
+- Deadline: 26-02-2026
+- Size: medium
+
+## Summary
+
+We want to adopt the abra wrapper Alakazam (https://git.coopcloud.tech/moritz/alakazam) , which is used by KolliCloud (https://kollicloud.de) as an official project in the Co-op Cloud Federation
+
+## Details
+
+As we already disscussed on our Meetup and the Alakazam workshop at 39C3 end of 2025, we want to adopt the abra wrapper Alakazam (https://git.coopcloud.tech/moritz/alakazam), which is used by KolliCloud (https://kollicloud.de) as an official project in the Co-op Cloud Federation. This way, we want to start collaborative effort on teaching, writing docs, writing tests.
+
+This includes the following (in the long run):
+
+* tranfering the Alakazam repository to https://git.coopcloud.tech/toolshed
+* creating a space in the docs for alakazam and moving the contents of the readme and the nessecary contents of https://wiki.local-it.org/s/kollicloud-wiki/doc/installation-wVp2LfBbg7
+* get others to try alakazam (future Kite-Flying sessions for this)
+* write tests for alakazam
+* implement the option to use more than one deployment of the same application in one instance
+* migrate alaconnect.yml files for the recipe (we have to figure out how multiple instances would allow this in regards to the multiple same apps in one instance)
+* migrate the features (that makes sense) into abra

docs/federation/resolutions/passed/036.md

@@ -0,0 +1,28 @@
+---
+title: "Resolution 036: Democratic Tech Fund joins the Co-op Cloud Federation"
+---
+
+- Topic: Resolution 036: Democratic Tech Fund joins the Co-op Cloud Federation
+- Date: 2026-01-19
+- Deadline: 2026-02-02
+- Size: Large
+
+## Summary
+
+The Democratic Tech Fund (DTF) is a Project-In-The-Making which has close affinity with Co-op Cloud in culture and stated goals. `@mikemh` and `@wtebbens` are active members of the community and can represent the Democratic Tech Fund. The DTF would like to join the Co-op Cloud Federation in order to establish a solid base for future collaboration.
+
+The DTF is set up as a co-operative federation, with multi-stakeholder membership: to allow both individual as organisational membership, operational members (i.e. workers), collaborator members, council of steward members (elected) and institutional members (public and private funders).
+
+A brief summary of the the intended goals of the DTF are as follows:
+
+* **Build and provide the tech**: Generating working configurations of tech infrastructure and services that address actual, perceived needs, drawing on the reserves of free-libre open- source software and constructing practices of material infrastructure that are under the review and steering of the communities they service. 
+
+* **Mobilise awareness towards adoption**: highlighting the clear and present danger and our collective capacity to resist, re-make and re-imagine. There's a need for campaign work, media and visuals, and for intelligence and news about what has already been done. 
+
+* **Build the community**: nurturing local, regional and trans-regional communities and networks that are capable to articulate these alternatives, to make the change together and to sustain the economic base for radically re-oriented infrastructure.
+
+Please see the latest Work-In-Progress [DTF concept note - v0.3](https://oficina.commonscloud.coop/s/No93qBkpxAsgYqE) for more details. Founding members include the [Free Knowledge Institute](https://freeknowledge.eu), [Commons Network](https://www.commonsnetwork.org) and [Fundación Platoniq / Goteo.org](https://goteo.org). The Free Knowledge Institute is also the fiscal host of the DTF. Please see the website of the [DTF](https://democratictech.fund) itself for more information.
+
+DTF are happy to pay the current recommended federation membership fee.
+
+Please feel free to join `#dtf2026:matrix.org` to keep up with DTF project developments.

docs/maintainers/maintain.md

@@ -64,15 +64,19 @@ See the [`.gitea/PULL_REQUEST_TEMPLATE.md`](https://git.coopcloud.tech/coop-clou
 ## Where can maintainers find support?
 
 ### Chat
+
 An active community exists in the [`#coopcloud-tech`](https://matrix.to/#/#coopcloud-tech:autonomic.zone?via=autonomic.zone) channel, which can answer your questions and help with issues. Please be patient when asking for support.
 
 ### Recipe Issue Tracker
+
 If you're stuck on a problem, create an issue in your recipe's issue tracker. Users of your repository may contribute PRs, otherwise you can ask the community for support.
 
 ### Toolshed
+
 If you're blocked by a problem in Coop Cloud's tooling, write a ticket to one of the [Toolshed](https://git.coopcloud.tech/toolshed) issue trackers. For example:
+
 * [abra](https://git.coopcloud.tech/toolshed/abra/issues)
 * [docs.coopcloud.tech](https://git.coopcloud.tech/toolshed/docs.coopcloud.tech/issues)
 * [recipes.coopcloud.tech](https://git.coopcloud.tech/toolshed/recipes.coopcloud.tech/issues)
 
-If you cannot find a repository to match your problem, you can write in the (organizing issues)[https://git.coopcloud.tech/toolshed/organising/issues] tracker. (See: [migration notice](https://git.coopcloud.tech/toolshed/organising/issues/667))
+If you cannot find a repository to match your problem, you can write in the [organizing issues](https://git.coopcloud.tech/toolshed/organising/issues) tracker. (See: [migration notice](https://git.coopcloud.tech/toolshed/organising/issues/667))

docs/operators/handbook.md

@@ -521,7 +521,9 @@ Yes, as of [`#585`](https://git.coopcloud.tech/toolshed/abra/pulls/585), this is
 ## Running an offline coop-cloud server 
 
 You may want to run a coop-cloud directly on your device (or in a VM or machine on your LAN), whether that's for testing a recipe or to run coop-cloud apps outside of the cloud ;-)
-In that case you might simply add some names to `/etc/hosts` (e.g `127.0.0.1 myapp.localhost`), or configure them on a local DNS server - which means `traefik` won't be able to use `letsencrypt` to generate and verify SSL certificates. Here's what you can do instead:
+
+In that case you might set up your server with `abra add server --local` like you would do it [running abra server side](#running-abra-server-side) (without a specific server name).
+Then you could simply add some names to `/etc/hosts` (e.g `127.0.0.1 myapp.localhost`, `127.0.0.1 coopcloud.local`, `127.0.0.1 *.coopcloud.local`), or configure them on a local DNS server - which means `traefik` won't be able to use `letsencrypt` to generate and verify SSL certificates. Here's what you can do instead:
 1. In your traefik .env file, edit/uncomment the following lines:
 ```
 LETS_ENCRYPT_ENV=staging
@@ -530,7 +532,8 @@ SECRET_WILDCARD_CERT_VERSION=v1
 SECRET_WILDCARD_KEY_VERSION=v1
 COMPOSE_FILE="$COMPOSE_FILE:compose.wildcard.yml"
 ```
-2. Generate a self-signed certificate using the [command listed here](https://letsencrypt.org/docs/certificates-for-localhost/#making-and-trusting-your-own-certificates). Unless using `localhost` you may want to edit that where it appears in the command, and/or add multiple (sub)domains to the certificate e.g: `subjectAltName=DNS:localhost,DNS:myapp.localhost`
+2. Generate a self-signed certificate using the [command listed here](https://letsencrypt.org/docs/certificates-for-localhost/#making-and-trusting-your-own-certificates). Unless using `localhost` you may want to edit that where it appears in the command, and/or add multiple (sub)domains to the certificate e.g: `subjectAltName=DNS:localhost,DNS:myapp.localhost`. You can also use wildcard-subdomains if you want to be more flexible later one, which apps to deploy: `subjectAltName=DNS:coopcloud.local,DNS:*.coopcloud.local`. 
+
 3. Run these commands:
 ```
 abra app secret insert localhost ssl_cert v1 localhost.crt -f

docs/operators/tutorial.md

@@ -262,7 +262,6 @@ abra app deploy <nextcloud-domain>
 ```
 abra app ps -w <nextcloud-domain>     # status check
 abra app logs <nextcloud-domain>      # logs trailing
-abra app errors -w <nextcloud-domain> # error catcher
 ```
 
 Your new `traefik` instance will detect that a new app is coming up and generate TLS certificates for it. You can see what `traefik` is up to using the same commands above but replacing `<nextcloud-domain>` with the `<traefik-domain>` you chose earlier (`abra app ls` will remind you what domains you chose :grinning:).

mkdocs.yml

@@ -94,6 +94,8 @@ nav:
         - federation/proposals/federation.md
       - "Resolutions":
           - federation/resolutions/index.md
+          - "Draft":
+              - federation/resolutions/index.md
           - "Passed":
               - federation/resolutions/passed/001.md
               - federation/resolutions/passed/002.md
@@ -127,11 +129,14 @@ nav:
               - federation/resolutions/passed/031.md
               - federation/resolutions/passed/033.md
               - federation/resolutions/passed/034.md
+              - federation/resolutions/passed/036.md
           - "Stalled":
               - federation/resolutions/stalled/013.md
               - federation/resolutions/stalled/030.md
           - "In Progress":
               - federation/resolutions/index.md
+              - federation/resolutions/in-progress/035.md
+              - federation/resolutions/in-progress/037.md
       - "Minutes":
           - federation/minutes/index.md
           - "Recently":
@@ -161,6 +166,7 @@ nav:
       - "Hack": abra/hack.md
       - "Troubleshoot": abra/trouble.md
       - "Cheat Sheet": abra/cheat-sheet.md
+      - "Swarm mode almanac": abra/swarm.md
   - "Specifications":
       - specs/index.md
       - "Backups":

requirements.txt

@@ -1,6 +1,6 @@
 mkdocs~=1.6.1
 
-mkdocs-material==9.5.49
+mkdocs-material==9.6.20
 mkdocs-material-extensions==1.3.1
 mkdocs-awesome-pages-plugin==2.10.1
 pygments==2.19.1