toolshed/docs.coopcloud.tech
3
1
Fork 21
Code Issues 4 Pull Requests 2 Packages Releases Activity

Compare commits

base: toolshed:main
Branches Tags
toolshed:main toolshed:R32 toolshed:lambdabundesverband-patch-1 toolshed:auto-menu toolshed:migrate-021 toolshed:resolutions-march toolshed:add/karrot-joining-resolution toolshed:decap-cms toolshed:010-budget-format toolshed:translation
..
compare: toolshed:R32
Branches Tags
toolshed:main toolshed:R32 toolshed:lambdabundesverband-patch-1 toolshed:auto-menu toolshed:migrate-021 toolshed:resolutions-march toolshed:add/karrot-joining-resolution toolshed:decap-cms toolshed:010-budget-format toolshed:translation

1 Commits
main ... R32

Author SHA1 Message Date
Ammar Hussein
7740ed80bf R32 2025-06-30 18:40:24 -07:00
4 changed files with 112 additions and 96 deletions
Expand all files Collapse all files

22
docs/federation/resolutions/in-progress/032.md Normal file
View File

@ -0,0 +1,22 @@
---
title: "Resolution 032"
---
- Topic: RTM joins Coopcloud
- Date: 2025-06-30
- Deadline: 2025-07-10
- Size: Large
### Summary
Ammar's membership was approved in [Resolution 022](/federation/resolutions/passed/022).
Since the establishment of RTM (Resist Rech Monopolies) collective in Seattle, Ammar has been unofficially representing the collective with coopcloud and vice versa.
### Details
RTM relies on the coop-cloud stack to host and manage their infrastructure, with the possibility of expanding this infrastructure to serve other communities and groups as the needs are identified and the capacity of the collective grows.
In a loomio decision, the collective approved pursuing a membership with the federation and Ammar is both happy to vouch and to yield their membership to the group.
This way this decision doesn't affect the total number of members.

95
docs/maintainers/catalogue.md
View File

@ -1,95 +0,0 @@
---
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.

89
docs/maintainers/handbook.md
View File

@ -421,6 +421,71 @@ 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.
@ -521,6 +586,30 @@ 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

2
mkdocs.yml
View File

@ -75,7 +75,6 @@ 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
@ -128,6 +127,7 @@ nav:
- federation/resolutions/index.md
- federation/resolutions/in-progress/030-docs-naming-survey.md
- federation/resolutions/in-progress/031.md
- federation/resolutions/in-progress/032.md
- "Minutes":
- federation/minutes/index.md
- "Recently":