forked from toolshed/docs.coopcloud.tech
Compare commits
2 Commits
main
...
lambdabund
| Author | SHA1 | Date | |
|---|---|---|---|
| 8922150994 | |||
| 1618faa420 |
@ -1,41 +0,0 @@
|
||||
---
|
||||
title: "Resolution 031"
|
||||
---
|
||||
|
||||
- Topic: Critical fixes amended process
|
||||
- Date: 2025-06-10
|
||||
- Deadline: 2025-06-24
|
||||
- Size: Medium
|
||||
|
||||
### Summary
|
||||
|
||||
This resolution proposes specific changes to [`R010: Budget 004: Critical
|
||||
fixes`](../passed/010.md). These changes are primarily intended to improve
|
||||
transparency and match our new organising methods.
|
||||
|
||||
## Details
|
||||
|
||||
Ammendments are as follows.
|
||||
|
||||
1. "Confirmation from at least one other member": should be confirmed on the
|
||||
issue itself and not in the Matrix chat. It is suggested to indicate this
|
||||
when posting in the Matrix chat (aka "Please +1 on the issue itself").
|
||||
1. "A fix is deemed critical": when it is marked with the label "critical fix".
|
||||
There is no specific project tracker for only these issues. This label can
|
||||
be re-used across repositories also.
|
||||
|
||||
### R010 in full
|
||||
|
||||
> We propose to have a standing budget of 10 hrs / month available for fixes in Abra, Co-op Cloud recipes and other critical tools (e.g. recipes.coopcloud.tech) in the Co-op Cloud ecosystem.
|
||||
>
|
||||
> A fix is deemed critical when it is listed on this toolshed/organising board:
|
||||
>
|
||||
> > https://git.coopcloud.tech/toolshed/organising/projects/24
|
||||
>
|
||||
> This board is collectively gardened by Co-op Cloud participants (both federation members and not). The process for adding a ticket to the board requires getting confirmation from at least one other member of the federation.
|
||||
>
|
||||
> This budget can be claimed by any volunteer who would like to develop the fix. If the volunteer is not a Co-op Cloud federation member, they must first be "vouched for" by a federation member. This is an informal process which can be arranged via the Matrix chat. This aims to assure agreement on timing and what the fix should contain beforehand.
|
||||
>
|
||||
> Fixes can be claimed by assiging yourself to the ticket. If within 1 week there is no updates on the ticket, another volunteer can propose to take over. This process is also informal: please @ the original volunteer and give some reasonable time for them to reply (suggested: 1 day).
|
||||
>
|
||||
> If the fix is urgent and things need to move faster, please state so on the ticket. Please consult with at least one other member of the federation to confirm that there is indeed agreement on the urgency of the fix.
|
||||
@ -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.
|
||||
|
||||
@ -124,6 +124,45 @@ You can also access it in your configs using the following syntax:
|
||||
{{ env "FOO" }}
|
||||
```
|
||||
|
||||
### Example: Adding environment variables to existing recipe
|
||||
Here is a four step example how to add a new environment variable to a recipe without breaking existing deployments.
|
||||
|
||||
1. add env-var to the `compose.yml` in section `environment`:
|
||||
```yaml
|
||||
environment:
|
||||
# ... existing envs
|
||||
- REQUIRE_AUTH_FOR_PROFILE_REQUESTS=${REQUIRE_AUTH_FOR_PROFILE_REQUESTS:-false}
|
||||
# ... other existing envs
|
||||
```
|
||||
|
||||
With `${REQUIRE_AUTH_FOR_PROFILE_REQUESTS:-false}` you set a default value (`false`), ensuring not to break existing deployments.
|
||||
If you're sure that it won't cause problems, if operators of existing deployments don't set the variable, you could also just put:
|
||||
```yaml
|
||||
environment:
|
||||
# ... existing envs
|
||||
- REQUIRE_AUTH_FOR_PROFILE_REQUESTS
|
||||
# ... other exisitng envs
|
||||
```
|
||||
|
||||
Note: If you need to break something, make sure to add a [release note](/maintainers/handbook/#how-do-i-write-version-release-notes) explaining to operators what they should change before upgrading.
|
||||
|
||||
2. add env-var to the `.env.sample`
|
||||
```yaml
|
||||
#REQUIRE_AUTH_FOR_PROFILE_REQUESTS=true
|
||||
```
|
||||
|
||||
3. now you can use the environment-variable in your `.tmpl` files, e.g. add to `homserver.yaml.tmpl`
|
||||
```yaml
|
||||
require_auth_for_profile_requests: {{ env "REQUIRE_AUTH_FOR_PROFILE_REQUESTS" }}
|
||||
```
|
||||
|
||||
4. increase number of YAML-version in `abra.sh` (e.g. from `v30` to `v31`), only then it will be deployed.
|
||||
```yaml
|
||||
export HOMESERVER_YAML_VERSION=v31
|
||||
```
|
||||
|
||||
Note: If during development and testing you have to increase it several times, you can just "flatten" it in the end. Only make sure that you `undeploy`/`deploy` your existing instance.
|
||||
|
||||
### Global environment variables
|
||||
|
||||
- `TYPE`: specifies the recipe name
|
||||
@ -402,24 +441,70 @@ You can also add release notes for the next release into a special file `release
|
||||
|
||||
This feature is only available in the > 0.9.x series of `abra`.
|
||||
|
||||
## How do I know whether to accept version upgrades when running `abra recipe upgrade <something>`?
|
||||
## How do I generate the recipe catalogue
|
||||
|
||||
### Postgres
|
||||
To generate an entire new copy of the catalogue:
|
||||
|
||||
Beware major Postgres version updates!
|
||||
```
|
||||
abra catalogue generate
|
||||
```
|
||||
|
||||
"Major" updates are ones where the first number changes, for example 14 to 15 (or 14.1 to 15.1).
|
||||
You will most likely want to pass `--user/--username` / `--pass/--password` with container regsitry credentials to avoid rate limiting.
|
||||
|
||||
Postgres cannot update itself, so accepting major version upgrades can break existing app deployments.
|
||||
If you just want to generate a catalogue entry for a single recipe:
|
||||
|
||||
To check if a recipe can handle upgrades:
|
||||
```
|
||||
abra catalogue generate <recipe>
|
||||
```
|
||||
|
||||
1. Check whether the recipe is using the `pgautoupgrade` image.
|
||||
2. Check whether the recipe contains a custom postgres entrypoint, `entrypoint.postgres.sh`.
|
||||
The changes are generated and added to `~/.abra/catalogue`, you can validate what is done by running:
|
||||
|
||||
If neither #1 nor #2 is true, **do not include a "major" postgres upgrade in a recipe upgrade**.
|
||||
```
|
||||
cd ~/.abra/catalogue
|
||||
git diff
|
||||
```
|
||||
|
||||
Feel welcome to ask for help in #coopcloud-tech:matrix.autonomic.zone
|
||||
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
|
||||
|
||||
@ -521,6 +606,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
|
||||
@ -646,11 +755,6 @@ Please note:
|
||||
1. The `file_env` / `_FILE` hack is to pass secrets into the container runtime without exposing them in plaintext in the configuration. See [this entry](/maintainers/handbook/#exposing-secrets) for more.
|
||||
|
||||
1. In order to pass execution back to the original entrypoint, it's a good idea to find the original entrypoint script and run it from your own entrypoint script. If there is none, you may want to reference the `CMD` definition or if that isn't working, try to actually specify `cmd: ...` in the `compose.yml` definition (there are other recipes which do this).
|
||||
|
||||
1. Also it might be necessary to define command: although there is an original entrypoint. That's [due to the fact](https://docs.docker.com/reference/compose-file/services/#entrypoint) that if entrypoint is non-null, Compose ignores any default command from the image, for example the `CMD` instruction in the Dockerfile.
|
||||
|
||||
1. Pratically you would e.g. look for the Dockerfile of the upstream image. In there you should find the docker-entrypoint.sh (or similar) and where it's located. Furthermore you find the `CMD`-line there.
|
||||
1. Just put in your entrypoint.sh in the last line: exec /path/to/docker-entrypoint.sh "@" (path and filename you should find in upstream Dockerfile) and insert command: to your service in compose.yml with the value of what you find in the CMD line of the Dockerfile.
|
||||
|
||||
1. If you're feeling reckless, you can also use the Golang templating engine to do things conditionally.
|
||||
|
||||
|
||||
@ -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
|
||||
@ -127,7 +126,6 @@ nav:
|
||||
- "In Progress":
|
||||
- federation/resolutions/index.md
|
||||
- federation/resolutions/in-progress/030-docs-naming-survey.md
|
||||
- federation/resolutions/in-progress/031.md
|
||||
- "Minutes":
|
||||
- federation/minutes/index.md
|
||||
- "Recently":
|
||||
|
||||
Reference in New Issue
Block a user