docs: describe the C4DT fork in README and README_C4DT.md

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Linus Gasser
2026-11-20 17:11:16 +01:00
co-authored by Claude Opus 5.5
parent 9170b4d23a
commit ea1dd3e62c
2 changed files with 36 additions and 0 deletions
+4
View File
@@ -5,6 +5,10 @@
[![Go Reference](https://pkg.go.dev/badge/coopcloud.tech/abra.svg)](https://pkg.go.dev/coopcloud.tech/abra)
[![Translation status](https://translate.coopcloud.tech/widget/co-op-cloud/svg-badge.svg)](https://translate.coopcloud.tech/engage/co-op-cloud/)
> [!NOTE]
> This is an LLM-modified version of `abra`, based on upstream [`toolshed/abra`](https://git.coopcloud.tech/toolshed/abra) `main` of 2026-11-18 (`0.13.0-beta` + 163 commits, `9023bb87`).
> See [README_C4DT.md](README_C4DT.md) for the differences.
The Co-op Cloud utility belt 🎩🐇
<a href="https://github.com/egonelbre/gophers"><img align="right" width="150" src="https://github.com/egonelbre/gophers/raw/master/.thumb/sketch/adventure/poking-fire.png"/></a>
+32
View File
@@ -0,0 +1,32 @@
# C4DT changes to `abra`
This fork of [`toolshed/abra`](https://git.coopcloud.tech/toolshed/abra) is maintained by C4DT. The changes were made with the help of an LLM coding assistant.
It is based on upstream `main` at commit `9023bb87` of 2026-11-18, which is 163 commits after the `0.13.0-beta` tag.
## Overview
| Change | Summary |
| --- | --- |
| [Digest pinning](#digest-pinning) | Recipes can pin images to a digest; `abra recipe upgrade` keeps the pin up to date |
| [`abra audit`](#abra-audit) | Checks all deployed apps against reviewed advisories and suggests fixes that are verified to exist |
| [Type remote](#type-remote) | Recipes can come from any git URL, and be pinned to a branch, in `RECIPE=` |
| [Devbox](#devbox) | `devbox.json` with the toolchain, and `build` and `test` scripts |
## Details
### Digest pinning
Some upstream images, such as `nextcloud`, are rebuilt under the same tag, so the tag alone cannot tell a vulnerable image from a fixed one. Recipes can now pin an image to a digest, for example `nextcloud:34.0.5-fpm@sha256:...`. `abra recipe upgrade` keeps the digest in sync: when it moves a pinned image to a new tag, it writes the new tag's digest, and when the current tag was re-published upstream, it warns and offers to update the pin. A pinned digest also makes a failed registry lookup at deploy time visible, instead of Docker silently keeping an old local image. To support this, `pkg/client/registry.go` gained `GetRegistryDigest`, which returns the index digest that Docker resolves `image:tag` to, and now requests OCI image indexes, which many multi-arch images on Docker Hub require. Commit `e5804d22`.
### `abra audit`
`abra audit` checks every deployed app on every server against the reviewed advisories in [`c4dt/advisories`](https://git.coopcloud.tech/c4dt/advisories), which it pulls on every run. It reads the recipe version and the image digests from each service spec, and the image configs (build time, environment such as `PHP_VERSION`, version labels) from the server's Docker daemon, or from the registry for the server's platform. Advisories match by recipe version range, environment version range, image version, build time, and known-good or known-bad digests. Before suggesting a fix, the audit checks that it works: a redeploy is only suggested if the tag's current image is fixed, and a recipe upgrade names the oldest release whose images are fixed. If no release fixes the problem yet, it says so and warns; recipe repositories are only read from their release tags, so local checkouts are never changed. The output is a short numbered table of failing apps followed by a numbered list of fixes, and the exit code is 1 when anything fails. Unlike the rest of abra, the audit needs an explicitly chosen abra directory (`$ABRA_DIR` or `abraDir` in `abra.yaml`) and never falls back to `~/.abra`. The design, including the planned later versions, is in [`doc/DesignAudit.md`](doc/DesignAudit.md). Commits `e07454ec`, `d699e51c`, `165a81de`, `491ea47f`, `d6912414`, `6fc26afa`.
### Type remote
Recipes no longer have to come from the catalogue. `abra app new` accepts a git URL in any common form (`https://`, `ssh://`, `git@host:path`), which is normalized to a canonical `host/path` name, and the app's `.env` gets a `RECIPE=<host/path>` line so that a later deploy, possibly on another machine, fetches the recipe from the same source. The clone records its source in a `.abra-source` file, and `abra recipe ls` shows these external recipes in a source column. The `:<version>` suffix in `RECIPE=` may now also be a branch name: it is fetched on demand into `refs/remotes/origin/*` and checked out at its tip as a chaos commit, after tags and commit hashes, and fails clearly in offline mode if the branch was never fetched. The deployed version is now stored in a single `.env` field, and upgrade and rollback set the version label themselves, because git-URL recipes often carry a stale label in `compose.yml`. Cherry-picked from `ineiti/abra` branch `type_remote` (commits `73227c9e`, `0a157896`, `0c91585e`, `47d9f732`, `5f80d5e8`); `9170b4d2` fixes one of its tests, which did not test the unfetched case it was named for.
### Devbox
A `devbox.json` pins the toolchain (Go 1.27, make, gettext): `devbox run build` builds abra, and `devbox run test` runs the tests with a temporary `ABRA_DIR`, which the existing tests require. Along with it, the `vendor/` directory was regenerated with `go mod vendor`, because it was out of sync with `go.mod` after an upstream dependency update and the default build failed. A binary built with a plain `go build`, without the `-ldflags` that set the commit, no longer panics: commit hashes are now truncated safely, and the default commit is `unknown-commit`. Commits `4e88ff9d`, `d699e51c`, `907a7eaa`, `2f0f3880`, `836971d6`.