forked from toolshed/docs.coopcloud.tech
docs: new versioning scheme incoming
This commit is contained in:
@ -1,8 +1,8 @@
|
||||
---
|
||||
title: Packager guide
|
||||
title: Recipe maintainer guide
|
||||
---
|
||||
|
||||
## Package your first application
|
||||
## Package your first recipe
|
||||
|
||||
Let's take as an example, [Matomo web analytics](https://matomo.org/).
|
||||
|
||||
@ -55,7 +55,7 @@ abra app new matomo --secrets \
|
||||
--domain matomo.swarm.example.com \
|
||||
--server swarm.example.com \
|
||||
--app-name mygreatapp
|
||||
```
|
||||
```
|
||||
|
||||
Depending on whether you defined any extra environment variables -- we didn't so
|
||||
far, in this example -- you might want to run `abra app mygreatapp config` to
|
||||
@ -69,103 +69,26 @@ abra app mygreatapp deploy
|
||||
|
||||
Then, open the `DOMAIN` you configured (you might need to wait a while for Traefik to generate SSL certificates) to finish the set-up. Luckily, this container is (mostly) configurable via environment variables -- if we want to auto-generate the configuration we can use a `config` and / or a custom `entrypoint` (see [`coop-cloud/mediawiki`](https://git.autonomic.zone/coop-cloud/mediawiki) for examples of both).
|
||||
|
||||
## How apps are versioned
|
||||
## How recipes are versioned
|
||||
|
||||
Co-op Cloud follows the version scheme of the applications we're packaging, as
|
||||
far as possible; for example, [version `1.13.4` of our Gitea recipe][gitea]
|
||||
contains version `1.13.4` of Gitea. We're trying not to invent a new versioning
|
||||
scheme.
|
||||
> We are still working on stabilising this workflow
|
||||
|
||||
This approach is still work-in-progress.
|
||||
We'll use an example to work through this. Let's use [Gitea](https://hub.docker.com/r/gitea/gitea).
|
||||
|
||||
Versions are based on [Docker image tags][tags]: we don't currently have a plan for apps
|
||||
which only publish a `latest` or `master` tag, for instance.
|
||||
The Gitea project maintains a version, e.g. `1.14.3`. This version uses the [semver](https://semver.org) strategy for communicating what type of changes are included in each version, i.e., if there is a breaking change, Gitea will release a new version as `2.0.0`.
|
||||
|
||||
### Versioning different services
|
||||
However, there are other types of changes that can happen for a recipe. Perhaps the database image gets a breaking update or the actual recipe configuration changes some environment variable. This can mean that end-users of the recipe need to do some work to make sure their updates will deploy successfully.
|
||||
|
||||
Most apps have underlying services like databases and/or caches.
|
||||
Therefore, we maintain an additional version part, in front of the project version. So, the first release of the Gitea recipe in the Co-op Cloud project has the version of `1.0.0+1.14.3-rootless`. This `x.y.z+` is the version part that the recipe maintainer manages. If a new available Gitea version comes out as `1.15-rootless` then the recipe maintainer will publish `1.1.0+1.15-rootless` as this is a backwards compatible update, following semantic versioning.
|
||||
|
||||
When there's a new version of one of these services, but not the "main" service,
|
||||
we add/increment the `_<revision>` part at the end of the version.
|
||||
In all cases, we follow the semver semantics. So, if we upgrade the Gitea recipe from `1.14.3-rootless` to `1.15.3-rootless`, we still publish `1.1.0+1.15.3-rootless` as our recipe version. In this case, we skipped a few patch releases but it was all backwards compatible, so we only increment the minor version part.
|
||||
|
||||
So, if you are still on `1.13.4` for Gitea, but you have `mariadb:10.6` upgraded
|
||||
from `mariadb:10.5`, then the Gitea recipe package version would be `1.13.4_1`.
|
||||
The commands uses for dealing with this logic in `abra` are:
|
||||
|
||||
If you run `abra recipe gitea versions`, you'll see that there are a few
|
||||
available versions of the `gitea` recipe, two with the same version of the
|
||||
`gitea` image:
|
||||
- `abra recipe upgrade`: upgrade the image tags in the compose configs of a recipe
|
||||
- `abra recipe tag`: publish a git tag for the recipe repo
|
||||
- `abra recipe sync`: upgrade the deploy labels to match the new recipe version
|
||||
|
||||
```
|
||||
1.14.1-rootless:
|
||||
- app (gitea/gitea:1.14.1-rootless, 6244e9fc)
|
||||
- db (mariadb:10.5, 36288c67)
|
||||
1.14.1-rootless_1:
|
||||
- app (gitea/gitea:1.14.1-rootless, 6244e9fc)
|
||||
- db (mariadb:10.6, 718cb856)
|
||||
1.14.2-rootless:
|
||||
- app (gitea/gitea:1.14.2-rootless, bedf8d12)
|
||||
- db (mariadb:10.6, 718cb856)
|
||||
```
|
||||
|
||||
Versions `1.14.1-rootless` and `1.14.1-rooless_1` differ only in their version
|
||||
of the `mariadb` service. If there had been several updates to the `mariadb`
|
||||
image in between updates to the `gitea` image, there might have also been
|
||||
`1.14.1-rooless_2`, `1.14.1-rooless_3` -- this is more likely with recipes which
|
||||
include services with several different images.
|
||||
|
||||
!!! note
|
||||
|
||||
Not all of these updates will be released as installable Co-op Cloud recipes
|
||||
-- in this example, there's no version with `gitea:1.14.2-rootless` and
|
||||
`mariadb:10.5`. If you need a specific combination, create a pull request or
|
||||
issue in the repository for the app recipe!
|
||||
|
||||
[gitea]: https://git.autonomic.zone/coop-cloud/gitea/src/tag/1.13.4
|
||||
[tags]: https://docs.docker.com/engine/reference/commandline/tag/
|
||||
|
||||
## Automation
|
||||
|
||||
### Upgrades
|
||||
|
||||
See [autonomic-cooperative/renovate-bot](https://git.autonomic.zone/autonomic-cooperative/renovate-bot).
|
||||
|
||||
### Releases
|
||||
|
||||
```
|
||||
---
|
||||
kind: pipeline
|
||||
name: recipe release
|
||||
steps:
|
||||
- name: release a new version
|
||||
image: thecoopcloud/drone-abra:latest
|
||||
settings:
|
||||
command: recipe YOURRECIPE release
|
||||
deploy_key:
|
||||
from_secret: abra_bot_deploy_key
|
||||
```
|
||||
|
||||
### Failure notifications
|
||||
|
||||
```yaml
|
||||
- name: notify coopcloud-dev on failure
|
||||
image: plugins/matrix
|
||||
settings:
|
||||
homeserver: https://matrix.autonomic.zone
|
||||
roomid: "IFazIpLtxiScqbHqoa:autonomic.zone"
|
||||
userid: "@autono-bot:autonomic.zone"
|
||||
accesstoken:
|
||||
from_secret: autono_bot_access_token
|
||||
depends_on:
|
||||
- deployment
|
||||
when:
|
||||
status:
|
||||
- failure
|
||||
```
|
||||
|
||||
### Github mirroring
|
||||
|
||||
See [auto-mirror](https://git.autonomic.zone/coop-cloud/auto-mirror).
|
||||
|
||||
## Packaging style guide
|
||||
## Style guide
|
||||
|
||||
- Please don't use `&image` YAML repeat anchors on the `image: ...` key because our `recipe release` logic does not handle it (see [#172](https://git.autonomic.zone/coop-cloud/abra/issues/172))
|
||||
@ -39,7 +39,7 @@ nav:
|
||||
- Deploy your first app: deploy.md
|
||||
- App catalogue: apps.md
|
||||
- App config guide: app-config-guide.md
|
||||
- Packager guide: packager-guide.md
|
||||
- Recipe maintainer guide: recipe-maintainer-guide.md
|
||||
- Frequently asked questions: faq.md
|
||||
- Contributing guide: contribute.md
|
||||
- Community organising: comm-org.md
|
||||
|
||||
Reference in New Issue
Block a user