Files
kawaiipunk 4d67caff56
All checks were successful
continuous-integration/drone/push Build is passing
Improving the catalogue docs
2025-07-02 12:56:16 +01:00

4.8 KiB
Raw Permalink Blame History

title
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 "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 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 if you want to add your recipe to the catalogue.

In the future, we'd like to support multiple catalogues.

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 (probably using abra recipe release), it automatically does the recipe catalogue generation steps"

  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
  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 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?" 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.