Skip to content

Versioning and compatibility

Product and component versions

The RAG Platform has a product version, the version of rag-docker. Each product version pins exactly one version of each component it deploys.

Category Example Defined by
Product version RAG Platform 1.1.0 git tag of rag-docker
Component version RAG Web 1.1.0, RAG System 1.1.0 git tag of the component repository

All versions use semantic versioning (MAJOR.MINOR.PATCH). For an operator, the product version says what an upgrade takes:

Change Meaning for you
MAJOR Action required beyond replacing the deployment files and pulling, for example a new or renamed .env variable, a manual data migration or a database change. The release notes list every step
MINOR New features. No action: replace the files, pull, restart
PATCH Fixes and image updates. No action

The product MAJOR doesn't follow the component MAJORs. A component MAJOR raises the product MAJOR only if operators have to act.

These docs follow the product version: one docs version per MINOR release (1.1 covers 1.1.0 and later 1.1.x patches).

Supported combinations

compatibility.json in rag-docker records the supported component versions for each product version. The image digests let you check that you run exactly the released images.

Product RAG Web RAG System Internal contract PostgreSQL Valkey RabbitMQ
1.1.0 1.1.0 1.1.0 1 18.1 9.0.7 4.4.0
1.0.0 1.0.5 1.0.4 1 18.1 9.0 4
Image digests for 1.1.0
Image Digest
rag-web/web-gateway:1.1.0 sha256:9e30a2b7a0f0f41e328914080ce6256e9f5d0b4dc55c29b3fa7cd7fa45f79293
rag-web/web-gateway-migrations:1.1.0 sha256:cd7080d904ceea3c81b35521da60f39837ee958579f343e8d029baa9ea7b6bd6
rag-system/api-gateway:1.1.0 sha256:46ddc607bb8a351f1229df15aa2da67e46a2005567deff062411c882571b1528
rag-system/dlq-consumer:1.1.0 sha256:d6b2602bd4cb09f6a28314f8600d75544dd2d9d42ba7f13fa4876f49c5c73bb1
rag-system/ingestion:1.1.0 sha256:7ca82533c4c4944bb1cff6aa269c47a0744c026d33d84f78c0a2ab96017ac377
rag-system/postgres:1.1.0 sha256:a9a8cc37ca8f192eec46718e5179b139da830c523568d25bcc357de12dd1f710
rag-system/migrations:1.1.0 sha256:43e7cbd612bcafe10319ff10a7afc46f303d83bf37d0caa36132f1e8e9af3d45

All images are under registry.git.nrw/ki-expertisezentrum.nrw/apps/rag/. Compare with:

docker image inspect --format '{{index .RepoDigests 0}}' IMAGE:1.1.0

The internal contract is an integer for the API between RAG Web and RAG System. It changes only when that API changes in a way that breaks RAG Web.

Check what is running

GET /version on RAG Web doesn't need an API key:

{"component": "rag-web", "version": "1.1.0", "sha": "<full commit sha>", "product": "1.1.0"}
Field Meaning
component Always rag-web
version RAG Web version. Untagged builds report 0.0.0-dev+<short sha>
sha Full commit SHA of the build
product Product release, from APP_RELEASE set by the deployment files. null if unset

RAG System's api-gateway answers GET /version on the internal network with the same fields plus "contract": 1. RAG System services also log their version at startup.

Image tags

Release images are published as :<version> (for example :1.1.0) and as :sha-<short sha>. Neither tag is ever overwritten. The older :<short sha> tag is deprecated. Every image carries the OCI labels org.opencontainers.image.version, .revision, .created, .source and .title.