4.8 KiB
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"
- 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
- 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.
- Make sure there is a
generate recipe catalogue
step in the recipe's.drone.yml
-- if there isn't, you can copy the one fromcoop-cloud/rallly
unchanged. - 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.