docs: R021

modifying shell rc files don't have immediate effect and it's confusing
if you don't know this.

docs/abra/cheat-sheet.md

@@ -15,6 +15,8 @@ Definitely set up autocomplete or you'll be sad :sob: `abra` supports `bash`,
 
 ```
 $ abra autocomplete bash
+# Restart your terminal or load autocompletion in place
+$ source /etc/bash_completion.d/abra
 ```
 
 

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

@@ -0,0 +1,57 @@
+---
+title: "Resolution 021"
+---
+
+- Topic: Budget 011: Migrate to Cobra
+- Date: 18-07-2024
+- Deadline: 31-07-2024
+- Size: Large
+
+### Summary
+
+Migrate away from our current command-line dependency so `abra` usage is more predictable. The goal is to maintain feature parity with no breaking changes. The main advantage that we will get is robust and flexible handling of flags/arguments which don't depend on forcing a specific order (see [`#581`](https://git.coopcloud.tech/coop-cloud/organising/issues/581)). There are other bonuses such as built-in support for auto-completion, better handling of example usage, improved support for global flags (`--debug`) and manpage support.
+
+### Details (Budget 011)
+
+#### The problem
+
+The current help output of `abra app deploy` is as follows:
+
+`abra app deploy [command options] <domain> [<version>]`
+
+However, it is possible to do both of the following:
+
+```
+abra app deploy --chaos example.org  # "before" style
+abra app deploy example.org --chaos  # "after" style
+```
+
+However, `abra app cmd` is broken if you try to use the "after" style:
+
+```
+abra app cmd <domain> <function> --local -- <args>
+```
+
+This results in `<recipe> doesn't have a --local function` which is a bug in the `abra` code. It tries to read the position of the arguments but `--local` is included as an argument. The bug in `abra` is due to a bug in `urfave/cli` - "after" style options appear as arguments 😱
+
+The only way to use `abra app cmd` right now is using the "before" style:
+
+```
+abra app cmd  --local <domain> <function> -- <args>
+```
+
+This means that some commands allow both "after" and "before" style and some only allow "before" style. This is a source of confusion, raised issues and frustration.
+
+#### The solution
+
+[Several](https://git.coopcloud.tech/coop-cloud/abra/pulls/404) [attempts](https://git.coopcloud.tech/coop-cloud/abra/pulls/435) have been made to upgrade `urfave/cli` to fix this behaviour. However, as it turns out, it is **highly unlikely** that they will fix this upstream: [`urfave/cli#1950`](https://github.com/urfave/cli/issues/1950) [`urfave/cli#1928`](https://github.com/urfave/cli/pull/1928) (and even this proposal does not really include the desired robust flexible handling we need).
+
+`@decentral1se` has done a spike to confirm that [`cobra`](https://cobra.dev) handles flexible handling of arguments/flags. Those reading this proposal and wishing to try it out for themselves can take [Hugo](https://gohugo.io/) for a spin (it uses `cobra` as the underlying command-line library).
+
+This tool is well maintained and used by several large projects such as Hugo and Kubernetes. The library matches all functionality we require.
+
+#### Budget
+
+`@decentral1se` can carry out this work.
+
+Proposed budget of 15 hrs: `15 hrs * 20 = 300 EUR`

docs/operators/tutorial.md

@@ -32,15 +32,25 @@ You need to keep port `:80` and `:443` free on your server for web proxying to y
     Docker.
 
 ```
+# ssh into your server
+ssh <server-domain>
+
 # docker install convenience script
 wget -O- https://get.docker.com | bash
 
 # add user to docker group
 sudo usermod -aG docker $USER
 
-# setup swarm
+# exit and re-login to load the group
+exit
+ssh <server-domain>
+
+# back on the server, setup swarm
 docker swarm init
 docker network create -d overlay proxy
+
+# now you can exit and start using abra
+exit
 ```
 
 ??? question "Do you support multiple web proxies?"
@@ -82,7 +92,8 @@ abra -h
 ```
 
 You may need to add the `~/.local/bin/` directory to your `$PATH` variable, in
-order to run the executable.
+order to run the executable. Also, run this line into your terminal so
+you have immediate access to `abra` on the current terminal.
 
 ```bash
 export PATH=$PATH:$HOME/.local/bin

mkdocs.yml

@@ -130,6 +130,7 @@ nav:
           - federation/resolutions/passed/020.md
         - "In Progress":
           - federation/resolutions/in-progress/013.md
+          - federation/resolutions/in-progress/021.md
       - "Minutes":
         - federation/minutes/index.md
         - "Recently":