Karrot Docs

Appearance

Karrot release process ​

This doc explains how the build and release system works in Karrot.

🚧 Recently changed

This process has recently changed, so all a bit new!

Forgive us if some edges are rough.

Builds ​

When you push to main branch or a tag of karrot-frontend or
karrot-backend it triggers the CI to run a build process.

You can see the build job status over at karrot-frontend builds and karrot-backend builds .

These each build and publish a docker image.

karrot-frontend images:

bash
docker pull codeberg.org/karrot/karrot-frontend:latest

... and karrot-backend images:

bash
docker pull codeberg.org/karrot/karrot-backend:latest

Docker tags

The latest image tag refers to the main branch in git.

For tagged builds, the git tag and the docker tag is the same, e.g.:

bash
docker pull codeberg.org/karrot/karrot-frontend:v14.0.0
frontend .tar.gz archive

Additionally, the frontend is published as a tar.gz archive of the build files, ready for serving, see karrot-frontend archive.

This does not come with an appropriate nginx config, so you're on your own for that. You can borrow ideas from docker/nginx.conf.template.

Releases ​

Releases are found over at karrot/releases.

This brings together the frontend and backend images, the changelog, plus any release notes.

For each release, it gets a version number, e.g. v14.0.0.

We release both the frontend and backend with the same version number, and you must always run matching frontend/backends.

How to release a version ​

🚧 Work in progress

This might get refined into a single process in the future once the process settles down

Merge all changes ​

Make sure all changes you want to release are in the main branches of each repo.

Wait for tests and builds ​

Wait to see the main-branch tests and builds complete, and only proceed if they are successful.

Wait for deployment to dev.karrot.world ​

The latest version that has just been built will be automatically deployed to dev.karrot.world.

Check that deployment was successful, then go and visit it and check if your intended changes are working nicely!

Frontend ​

All changelong entries go in the frontend changelog file, so we need to update the first.

Update karrot-frontend/CHANGELOG.md:

  1. add your new release version in the [Unreleased] section with a date
  2. add entries for all changes made since previous release if it's not already been done
  3. prepare the release
bash
./scripts/prepare_release.js

Now we can push the frontend tag:

bash
git push
git push origin vYOUR.VERSION.NUMBER

Why two pushes?

The release script makes a commit to the main branch, then tags that, so we want to make sure remote main branch is up to date.

You could also use:

bash
git push --tags

Which does both (I think!), but maybe also pushes other tags.

Backend ​

This is easier, just tag and push:

bash
git tag vYOUR.VERSION.NUMBER
git push origin vYOUR.VERSION.NUMBER

Check builds again ​

Go and look at build status and see if they worked.

Optionally try them out ​

If you have a way to run Karrot with specific images, you could try out those built images yourself before proceed.

Example

I have a docker-compose.yml-based karrot setup on my local machine (using karrot/karrot/src/branch/main/docker-compose) where I can pop in an image reference and try it out to make sure it basically works.

Tag karrot/karrot ​

karrot/karrot is a repo that ties together the frontend and backend for the purposes of releases.

Make sure you have that checked out with the submodules:

bash
git clone --recurse-submodules https://codeberg.org/karrot/karrot

TIP

I have a clean checkout of this that is separate to my frontend/backend repos that I use when I'm coding. Up to you though.

Now we can create the release tag:

bash
./scripts/release-tag v14.0.1

This will:

  • pin the submodules to the right commit for that tag
  • create the tag in karrot/karrot
  • print a nice message telling you can push it
bash
git push --tags

Create the release ​

Go and visit https://codeberg.org/karrot/karrot/releases and press the "New Release" button.

Put in the tag you chose before, the name can also be the tag name.

For the description you want:

  1. a brief human description of the changes
  2. the info about how to get the docker images + tar.gz release (copy from a previous release and update tags)
  3. the changelog, you can just copy it from karrot-frontend changelog

Automation?

There is a good case for creating some automation for this, esp. creating the docker image info.

You can mark it as pre-release if you are not sure it's ready for consumption yet, then come back and uncheck that later.

Co-op Cloud recipe ​

Also, consider updating the Co-op Cloud Karrot recipe over at https://git.coopcloud.tech/coop-cloud/karrot.

Deploy to karrot.world on yuca ​

If you want to deploy it to karrot.world, your current option is by using ansible on your own machine.

See Using ansible directly.