diff --git a/docs/maintainers/catalogue.md b/docs/maintainers/catalogue.md new file mode 100644 index 0000000..9575ca3 --- /dev/null +++ b/docs/maintainers/catalogue.md @@ -0,0 +1,92 @@ +--- +title: The Recipe Catalogue +--- + +## 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 -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 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 +``` + +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. diff --git a/docs/maintainers/handbook.md b/docs/maintainers/handbook.md index 4526aaa..eddd952 100644 --- a/docs/maintainers/handbook.md +++ b/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 -``` - -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 -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 diff --git a/mkdocs.yml b/mkdocs.yml index 31aeb02..9d7ce7c 100644 --- a/mkdocs.yml +++ b/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