Moved Catalogue from handbook to new page
All checks were successful
continuous-integration/drone/push Build is passing
All checks were successful
continuous-integration/drone/push Build is passing
This commit is contained in:
92
docs/maintainers/catalogue.md
Normal file
92
docs/maintainers/catalogue.md
Normal file
@ -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 <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 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.
|
||||||
@ -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
|
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
|
## 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.
|
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.
|
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?
|
## How do I configure backup/restore?
|
||||||
|
|
||||||
From the perspective of the recipe maintainer, backup/restore is just more
|
From the perspective of the recipe maintainer, backup/restore is just more
|
||||||
|
|||||||
@ -75,6 +75,7 @@ nav:
|
|||||||
- maintainers/index.md
|
- maintainers/index.md
|
||||||
- "New Maintainers Tutorial": maintainers/tutorial.md
|
- "New Maintainers Tutorial": maintainers/tutorial.md
|
||||||
- "Packaging Handbook": maintainers/handbook.md
|
- "Packaging Handbook": maintainers/handbook.md
|
||||||
|
- maintainers/catalogue.md
|
||||||
- "Operators":
|
- "Operators":
|
||||||
- operators/index.md
|
- operators/index.md
|
||||||
- "New operators Tutorial": operators/tutorial.md
|
- "New operators Tutorial": operators/tutorial.md
|
||||||
|
|||||||
Reference in New Issue
Block a user