Improving the catalogue docs

docs/maintainers/catalogue.md

@@ -0,0 +1,95 @@
+---
+title: The Recipe Catalogue
+---
+
+## How are new recipes added to the catalogue?
+
+> This is so far a manual process which requires someone who's been added to the
+> `coop-cloud` "Organisation" on https://git.coopcloud.tech. 
+>
+> This is a temporary  situation, we want to open out this process & also introduce some automation 
+> to support making thie process more convenient. Please nag us to move things along on Matrix.
+
+- Publish your new recipe on the [git.coopcloud.tech](https://git.coopcloud.tech/coop-cloud) "Organisation"
+- Run `abra catalogue generate <recipe> -p`
+- Run `cd ~/.abra/catalogue && make`
+
+These minimal steps will publish a new recipe with no versions. You can also do
+the [recipe release publishing dance](https://docs.coopcloud.tech/maintainers/handbook/#how-do-i-release-a-new-recipe-version)
+which will then extend the `versions: [...]` section of the published JSON in the catalogue.
+
+Recipes that are not included in the catalogue can still be deployed. It is not
+required to add your recipes to the catalogue, but this will improve the
+visibility for other co-op hosters & end-users.
+
+For now, it is best to [get in touch](https://docs.coopcloud.tech/intro/contact/) if you want to add your recipe to the catalogue.
+
+In the future, we'd like to support [multiple catalogues](https://git.coopcloud.tech/toolshed/organising/issues/139).
+
+## How do I make the catalogue automatically regenerate after new recipe versions are published? 
+
+"I'd like to make it so that whenever I push a new git tag to the
+[`coop-cloud/rallly` repository](https://git.coopcloud.tech/coop-cloud/rallly)
+(probably [using `abra recipe
+release`](#how-do-i-release-a-new-recipe-version)), it automatically does the
+[recipe catalogue generation steps](#how-do-i-generate-the-recipe-catalogue)"
+
+1. Check whether tag builds are already trying to run: go to
+   https://build.coopcloud.tech, search for the recipe name (in this case taking
+   you to https://build.coopcloud.tech/coop-cloud/rallly/settings). If there are
+   failing builds, or if you see builds succeeding but catalogue regeneration
+   doesn't seem to be happening, then either dive in and try and fix it, or ask
+   for help in [`#coopcloud-tech`](https://matrix.to/#/#coopcloud-tech:autonomic.zone)
+2. Otherwise, click "activate repository". You probably want to set the "disable pull
+   requests" and "disable forks" options; they won't work anyway, but the
+   failures might be confusing.
+3. Make sure there is a `generate recipe catalogue` step in the recipe's
+   `.drone.yml` -- if there isn't, you can copy [the one from
+   `coop-cloud/rallly`](https://git.coopcloud.tech/coop-cloud/rallly/src/branch/main/.drone.yml#L24-L38) unchanged.
+4. That's it! Now, when you push a new tag, the recipe catalogue will regenerate
+   automatically. You can test this by re-pushing a tag (e.g. `git push origin
+   :0.5.0+3.5.1 && git push 0.5.0+3.5.1`)
+
+## How does automatic catalogue regeneration work?
+
+**TODO: write up properly**
+
+Context: the catalogue lives in a git repo here: https://git.coopcloud.tech/toolshed/recipes-catalogue-json
+
+The expectation is that this repo will only be updated automatically. While manual commits are possible, they're likely to be overwritten.
+
+Automatic regeneration is handled by this Drone step, in the separate `auto-recipes-catalogue-json` repo: https://git.coopcloud.tech/toolshed/auto-recipes-catalogue-json/src/branch/main/.drone.yml#L5-L25
+
+This is run on a daily schedule (question: where is `nightly-app-date` configured?), and can also be triggered by recipe repositories to make new versions available quicker – see "[How do I make the catalogue automatically regenerate after new versions are published?](#how-do-i-make-the-catalogue-automatically-regenerate-after-new-versions-are-published)" above.
+
+## How do I manually generate the recipe catalogue
+
+> These days, doing this is only useful in the event of troubleshooting the automatic catalogue regeneration
+
+To generate an entire new copy of the catalogue:
+
+```
+abra catalogue generate
+```
+
+You will most likely want to pass `--user/--username` / `--pass/--password` with container regsitry credentials to avoid rate limiting.
+
+If you just want to generate a catalogue entry for a single recipe:
+
+```
+abra catalogue generate <recipe>
+```
+
+The changes are generated and added to `~/.abra/catalogue`, you can validate what is done by running:
+
+```
+cd ~/.abra/catalogue
+git diff
+```
+
+You can pass `--publish` to have `abra` automatically publish those changes.
+
+!!! warning "Here be more SSH dragons"
+
+    In order to have `abra` publish changes for you automatically, you'll have to have write permissons to the git.coopcloud.tech repository and your account must have a working SSH key configuration. `abra` will use the SSH based URL connection details for Git by automagically creating an `origin-ssh` remote in the repository and pushing to it.
+

docs/maintainers/handbook.md

@@ -421,71 +421,6 @@ If neither #1 nor #2 is true, **do not include a "major" postgres upgrade in a r
 
 Feel welcome to ask for help in #coopcloud-tech:matrix.autonomic.zone
 
-## How do I generate the recipe catalogue
-
-To generate an entire new copy of the catalogue:
-
-```
-abra catalogue generate
-```
-
-You will most likely want to pass `--user/--username` / `--pass/--password` with container regsitry credentials to avoid rate limiting.
-
-If you just want to generate a catalogue entry for a single recipe:
-
-```
-abra catalogue generate <recipe>
-```
-
-The changes are generated and added to `~/.abra/catalogue`, you can validate what is done by running:
-
-```
-cd ~/.abra/catalogue
-git diff
-```
-
-You can pass `--publish` to have `abra` automatically publish those changes.
-
-!!! warning "Here be more SSH dragons"
-
-    In order to have `abra` publish changes for you automatically, you'll have to have write permissons to the git.coopcloud.tech repository and your account must have a working SSH key configuration. `abra` will use the SSH based URL connection details for Git by automagically creating an `origin-ssh` remote in the repository and pushing to it.
-
-## How do I make the catalogue automatically regenerate after new versions are published? 
-
-"I'd like to make it so that whenever I push a new git tag to the
-[`coop-cloud/rallly` repository](https://git.coopcloud.tech/coop-cloud/rallly)
-(probably [using `abra recipe
-release`](#how-do-i-release-a-new-recipe-version)), it automatically does the
-[recipe catalogue generation steps](#how-do-i-generate-the-recipe-catalogue)"
-
-1. Check whether tag builds are already trying to run: go to
-   https://build.coopcloud.tech, search for the recipe name (in this case taking
-   you to https://build.coopcloud.tech/coop-cloud/rallly/settings). If there are
-   failing builds, or if you see builds succeeding but catalogue regeneration
-   doesn't seem to be happening, then either dive in and try and fix it, or ask
-   for help in [`#coopcloud-tech`](https://matrix.to/#/#coopcloud-tech:autonomic.zone)
-2. Otherwise, click "activate repository". You probably want to set the "disable pull
-   requests" and "disable forks" options; they won't work anyway, but the
-   failures might be confusing.
-3. Make sure there is a `generate recipe catalogue` step in the recipe's
-   `.drone.yml` -- if there isn't, you can copy [the one from
-   `coop-cloud/rallly`](https://git.coopcloud.tech/coop-cloud/rallly/src/branch/main/.drone.yml#L24-L38) unchanged.
-4. That's it! Now, when you push a new tag, the recipe catalogue will regenerate
-   automatically. You can test this by re-pushing a tag (e.g. `git push origin
-   :0.5.0+3.5.1 && git push 0.5.0+3.5.1`)
-
-## How does automatic catalogue regeneration work?
-
-**TODO: write up properly**
-
-Context: the catalogue lives in a git repo here: https://git.coopcloud.tech/toolshed/recipes-catalogue-json
-
-The expectation is that this repo will only be updated automatically. While manual commits are possible, they're likely to be overwritten.
-
-Automatic regeneration is handled by this Drone step, in the separate `auto-recipes-catalogue-json` repo: https://git.coopcloud.tech/toolshed/auto-recipes-catalogue-json/src/branch/main/.drone.yml#L5-L25
-
-This is run on a daily schedule (question: where is `nightly-app-date` configured?), and can also be triggered by recipe repositories to make new versions available quicker – see "[How do I make the catalogue automatically regenerate after new versions are published?](#how-do-i-make-the-catalogue-automatically-regenerate-after-new-versions-are-published)" above.
-
 ## How do I enable healthchecks
 
 A healthcheck is an important and often overlooked part of the recipe configuration. It is part of the configuration that the runtime uses to figure out if a container is really up-and-running. You can tweak what command to run, how often and how many times to try until you assume the container is not up.
@@ -586,30 +521,6 @@ The possible Values are:
 
 The setting does only apply when you also set a length modifier to the secret (documented [here](/maintainers/handbook/#how-do-i-change-secret-generation-length)), so it is not applicable for the "easy to remember word" style generator that used when you don't set a length.
 
-## How are recipes added to the catalogue?
-
-> This is so far a manual process which requires someone who's been added to the
-> `coop-cloud` "Organisation" on https://git.coopcloud.tech. This is a temporary
-> situation, we want to open out this process & also introduce some automation
-> to support making thie process more convenient. Please nag us to move things
-> along.
-
-- Publish your new recipe on the [git.coopcloud.tech](https://git.coopcloud.tech/coop-cloud) "Organisation"
-- Run `abra catalogue generate <recipe> -p`
-- Run `cd ~/.abra/catalogue && make`
-
-These minimal steps will publish a new recipe with no versions. You can also do
-the [recipe release publishing dance](https://docs.coopcloud.tech/maintainers/handbook/#how-do-i-release-a-new-recipe-version)
-which will then extend the `versions: [...]` section of the published JSON in the catalogue.
-
-Recipes that are not included in the catalogue can still be deployed. It is not
-required to add your recipes to the catalogue, but this will improve the
-visibility for other co-op hosters & end-users.
-
-For now, it is best to [get in touch](https://docs.coopcloud.tech/intro/contact/) if you want to add your recipe to the catalogue.
-
-In the future, we'd like to support [multiple catalogues](https://git.coopcloud.tech/toolshed/organising/issues/139).
-
 ## How do I configure backup/restore?
 
 From the perspective of the recipe maintainer, backup/restore is just more

mkdocs.yml

@@ -75,6 +75,7 @@ nav:
       - maintainers/index.md
       - "New Maintainers Tutorial": maintainers/tutorial.md
       - "Packaging Handbook": maintainers/handbook.md
+      - maintainers/catalogue.md
   - "Operators":
       - operators/index.md
       - "New operators Tutorial": operators/tutorial.md