[WIP] switch to yhub as a collab backend

.github/workflows/impress.yml

@@ -27,10 +27,6 @@ jobs:
           fetch-depth: 0
       - name: show
         run: git log
-      - name: Enforce absence of print statements in code
-        if: always()
-        run: |
-          ! git diff origin/${{ github.event.pull_request.base.ref }}..HEAD -- src/backend ':(exclude)**/impress.yml' | grep "print("
       - name: Check absence of fixup commits
         if: always()
         run: |

.gitignore

@@ -47,6 +47,9 @@ env.d/terraform
 compose.override.yml
 docker/auth/*.local
 
+# yhub server local install
+src/yhub-server/node_modules/
+
 # npm
 node_modules
 

CHANGELOG.md

@@ -8,6 +8,9 @@ and this project adheres to
 
 ### Added
 
+- ✨(backend) add a service generating cached RS256 JWT tokens
+- ✨(backend) publish the JWT public key on a JWKS endpoint
+- 🔧(dev) generate the JWT signing key when bootstrapping the dev stack
 - ♿️(frontend) restore skip to content link after header redesign #2510
 - 🌐(i18n) rename cn_CN to zh_CN, add eo_PL and zh_TW locales #2486
 
@@ -17,7 +20,17 @@ and this project adheres to
 
 ### Changed
 
+- 💥(backend) move the resource server JWKS from `/api/{version}/jwks` to
+  `/external_api/{version}/jwks`
 - ♿️(frontend) use semantic `<dl>` structure in document info card #2379
+- ♻️(collaboration) migrate the collaboration server from hocuspocus to yhub:
+  the dev stack gains dedicated valkey and postgres services for yhub, and
+  the kick (reset-connections) and get-connections APIs have no yhub
+  equivalent yet — they are deferred with TODO(yhub) stubs
+- 💥(y-provider) the published `lasuite/impress-y-provider` image becomes
+  converter-only and no longer serves `/collaboration/ws/`; deployments using
+  the existing helm values lose collaboration until the helm chart routes
+  collaboration to yhub (follow-up)
 
 ## [v5.4.1] - 2026-07-09
 

Makefile

@@ -69,6 +69,11 @@ data/media:
 data/static:
 	@mkdir -p data/static
 
+# RSA key signing the JWT tokens the backend issues. Generated locally, never
+# committed: "data/" is gitignored. Regenerate it by deleting the file.
+data/jwt/private.pem:
+	@bin/generate-jwt-private-key.sh
+
 # -- Project
 
 create-env-local-files: ## create env.local files in env.d/development
@@ -81,7 +86,8 @@ create-env-local-files:
 .PHONY: create-env-local-files
 
 generate-secret-keys:
-generate-secret-keys: ## generate secret keys to be stored in common.local
+generate-secret-keys: ## generate the secret keys needed by the dev stack
+generate-secret-keys: data/jwt/private.pem
 	@bin/generate-oidc-store-refresh-token-key.sh
 .PHONY: generate-secret-keys
 
@@ -190,6 +196,7 @@ bootstrap-e2e: \
 build: cache ?=
 build: ## build the project containers
 	@$(MAKE) build-backend cache=$(cache)
+	@$(MAKE) build-yhub cache=$(cache)
 	@$(MAKE) build-yjs-provider cache=$(cache)
 	@$(MAKE) build-frontend cache=$(cache)
 .PHONY: build
@@ -199,9 +206,14 @@ build-backend: ## build the app-dev container
 	@$(COMPOSE) build app-dev $(cache)
 .PHONY: build-backend
 
+build-yhub: cache ?=
+build-yhub: ## build the yhub collaboration server container
+	@$(COMPOSE) build yhub $(cache)
+.PHONY: build-yhub
+
 build-yjs-provider: cache ?=
 build-yjs-provider: ## build the y-provider container
-	@$(COMPOSE) build y-provider-development $(cache)
+	@$(COMPOSE) build y-provider-development-converter $(cache)
 .PHONY: build-yjs-provider
 
 build-frontend: cache ?=
@@ -212,8 +224,9 @@ build-frontend: ## build the frontend container
 build-e2e: cache ?=
 build-e2e: ## build the e2e container
 	@$(MAKE) build-backend cache=$(cache)
+	@$(MAKE) build-yhub cache=$(cache)
 	@$(COMPOSE_E2E) build frontend $(cache)
-	@$(COMPOSE_E2E) build y-provider $(cache)
+	@$(COMPOSE_E2E) build y-provider-converter $(cache)
 .PHONY: build-e2e
 
 nginx-frontend: ## build the nginx-frontend container
@@ -230,10 +243,11 @@ logs: ## display app-dev logs (follow mode)
 
 run-backend: ## Start only the backend application and all needed services
 	@$(MAKE) create-docker-network
+	@$(MAKE) data/jwt/private.pem
 	@$(COMPOSE) up --force-recreate -d docspec
 	@$(COMPOSE) up --force-recreate -d celery-dev
-	@$(COMPOSE) up --force-recreate -d y-provider-development
 	@$(COMPOSE) up --force-recreate -d y-provider-development-converter
+	@$(COMPOSE) up --force-recreate -d yhub
 	@$(COMPOSE) up --force-recreate -d nginx
 .PHONY: run-backend
 
@@ -246,9 +260,7 @@ run:
 run-e2e: ## start the e2e server
 run-e2e:
 	@$(MAKE) run-backend
-	@$(COMPOSE_E2E) stop y-provider-development
 	@$(COMPOSE_E2E) up --force-recreate -d frontend
-	@$(COMPOSE_E2E) up --force-recreate -d y-provider
 	@$(COMPOSE_E2E) up --force-recreate -d y-provider-converter
 .PHONY: run-e2e
 

UPGRADE.md

@@ -16,6 +16,13 @@ the following command inside your docker container:
 
 ## [Unreleased]
 
+- The JWKS of the resource server moved from `/api/{version}/jwks` to
+  `/external_api/{version}/jwks`, alongside the rest of the resource server
+  endpoints. `/api/{version}/jwks` now publishes the public key validating the
+  tokens Docs issues to call external services. If you enabled the resource
+  server (`OIDC_RESOURCE_SERVER_ENABLED`), update the JWKS URI declared to your
+  OIDC provider accordingly.
+
 ### [5.0.0] - 2026-04-30
 
 We made several changes around document content management leading to several breaking changes in the API.

bin/_config.sh

@@ -38,6 +38,10 @@ function _set_user() {
 # options: docker compose command options
 # ARGS   : docker compose command arguments
 function _docker_compose() {
+    # The backend settings point at this key and the containers mount it, so it
+    # has to exist before any of them starts.
+    "${REPO_DIR}/bin/generate-jwt-private-key.sh"
+
     # Set DOCKER_USER for Windows compatibility with MinIO
     if [[ "$OSTYPE" == "msys" || "$OSTYPE" == "cygwin" || -n "${WSL_DISTRO_NAME:-}" ]]; then
         export DOCKER_USER="0:0"

bin/generate-jwt-private-key.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+
+# Generate the RSA private key signing the JWT tokens issued by the backend.
+#
+# Development only. The key is generated locally and never committed: it lands
+# in "data/", which is gitignored. The dev stack mounts it in the backend
+# containers, where JWT_PRIVATE_KEY_FILE points at it.
+#
+# Idempotent: an existing key is kept. Delete the file to roll the key.
+
+set -eo pipefail
+
+REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+KEY_PATH="${REPO_DIR}/data/jwt/private.pem"
+
+if [ -f "${KEY_PATH}" ]; then
+    exit 0
+fi
+
+mkdir -p "$(dirname "${KEY_PATH}")"
+openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out "${KEY_PATH}" 2>/dev/null
+chmod 600 "${KEY_PATH}"
+echo "✓ JWT private key generated in ${KEY_PATH}"

compose-e2e.yml

@@ -13,7 +13,7 @@ services:
     ports:
       - "3000:3000"
 
-  y-provider:
+  y-provider-converter:
     user: ${DOCKER_USER:-1000}
     build:
       context: .
@@ -24,16 +24,3 @@ services:
     env_file:
       - env.d/development/common
       - env.d/development/common.local
-    ports:
-      - "4444:4444"
-
-  y-provider-converter:
-    user: ${DOCKER_USER:-1000}
-    image: impress:y-provider-production
-    restart: unless-stopped
-    env_file:
-      - env.d/development/common
-      - env.d/development/common.local
-    depends_on:
-      y-provider:
-        condition: service_started

compose.yml

@@ -82,6 +82,7 @@ services:
     volumes:
       - ./src/backend:/app
       - ./data/static:/data/static
+      - ./data/jwt:/data/jwt:ro
       - /app/.venv
     depends_on:
       postgresql:
@@ -111,6 +112,7 @@ services:
     volumes:
       - ./src/backend:/app
       - ./data/static:/data/static
+      - ./data/jwt:/data/jwt:ro
       - /app/.venv
     depends_on:
       - app-dev
@@ -181,7 +183,7 @@ services:
     volumes:
       - ".:/app"
 
-  y-provider-development:
+  y-provider-development-converter:
     user: ${DOCKER_USER:-1000}
     build:
       context: .
@@ -192,27 +194,66 @@ services:
     env_file:
       - env.d/development/common
       - env.d/development/common.local
-    ports:
-      - "4444:4444"
     volumes:
       - ./src/frontend/:/home/frontend
       - /home/frontend/node_modules
       - /home/frontend/servers/y-provider/node_modules
 
-  y-provider-development-converter:
+  yhub-valkey:
+    image: valkey/valkey:alpine
+    # volatile-lru per yhub DEPLOYMENT.md; AOF because valkey is the authoritative store
+    # for updates the worker hasn't persisted yet (up to taskDebounce+minMessageLifetime)
+    command: ["valkey-server", "--maxmemory-policy", "volatile-lru",
+              "--appendonly", "yes", "--appendfsync", "everysec"]
+    volumes:
+      - yhub-valkey-data:/data
+    healthcheck:
+      test: ["CMD", "valkey-cli", "ping"]
+      interval: 1s
+      timeout: 2s
+      retries: 60
+
+  yhub-postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: yhub
+      POSTGRES_PASSWORD: yhub
+      POSTGRES_DB: yhub
+    volumes:
+      - yhub-pgdata:/var/lib/postgresql/data
+      # NOTE: initdb.d only runs on a FRESH volume; schema changes need `podman volume rm`
+      - ./docker/files/yhub/initdb:/docker-entrypoint-initdb.d:ro
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U yhub"]
+      interval: 1s
+      timeout: 2s
+      retries: 60
+    # no published port (Django's postgres already publishes)
+
+  yhub:
     user: ${DOCKER_USER:-1000}
-    image: impress:y-provider-development
-    restart: unless-stopped
+    build:
+      context: ./src/yhub-server
+      dockerfile: Dockerfile
+      target: yhub
+    image: impress:yhub
+    environment:
+      HOME: /tmp # same reason as node-based services above (unmapped uid)
+      PORT: 3002
+      REDIS: redis://yhub-valkey:6379
+      POSTGRES: postgres://yhub:yhub@yhub-postgres:5432/yhub
+      REDIS_PREFIX: yhub
     env_file:
       - env.d/development/common
       - env.d/development/common.local
-    volumes:
-      - ./src/frontend/:/home/frontend
-      - /home/frontend/node_modules
-      - /home/frontend/servers/y-provider/node_modules
+    restart: unless-stopped
+    ports:
+      - "3002:3002"
     depends_on:
-      y-provider-development:
-        condition: service_started
+      yhub-valkey:
+        condition: service_healthy
+      yhub-postgres:
+        condition: service_healthy
 
   kc_postgresql:
     image: postgres:14.3
@@ -268,3 +309,7 @@ networks:
     name: lasuite-network
     driver: bridge
     external: true
+
+volumes:
+  yhub-pgdata: {}
+  yhub-valkey-data: {}

docker/files/yhub/initdb/01-yhub.sql

@@ -0,0 +1,14 @@
+-- Column-for-column from yhub bin/init-db.js (unquoted identifiers so
+-- case-folding matches yhub's persistence.js queries).
+CREATE TABLE IF NOT EXISTS yhub_ydoc_v1 (
+    org             text,
+    docid           text,
+    branch          text,
+    t               text,
+    created         INT8,
+    gcDoc           bytea,
+    nongcDoc        bytea,
+    contentmap      bytea,
+    contentids      bytea,
+    PRIMARY KEY     (org,docid,branch,t)
+);

documentation/env.md

@@ -81,6 +81,8 @@ These are the environment variables you can set for the `impress-backend` contai
 | FRONTEND_JS_URL                                 | To add a external js file to the app                                                                                                                                       |                                                                         |
 | FRONTEND_HOMEPAGE_FEATURE_ENABLED               | Frontend feature flag to display the homepage                                                                                                                              | false                                                                   |
 | FRONTEND_THEME                                  | Frontend theme to use                                                                                                                                                      |                                                                         |
+| JWT_PRIVATE_KEY                                 | PEM encoded RSA private key used to sign the JWT tokens (RS256). Can be read from a file with JWT_PRIVATE_KEY_FILE                                                          |                                                                         |
+| JWT_TOKEN_LIFETIME                              | Lifetime in seconds of the generated JWT tokens. Also used as the cache timeout of these tokens                                                                             | 3600                                                                    |
 | LANGUAGE_CODE                                   | Default language                                                                                                                                                           | en-us                                                                   |
 | LANGFUSE_SECRET_KEY                             | The Langfuse secret key used by the sdk                                                                                                                                    | None                                                                    |
 | LANGFUSE_PUBLIC_KEY                             | The Langfuse public key used by the sdk                                                                                                                                    | None                                                                    |

documentation/resource_server.md

@@ -20,6 +20,11 @@ OIDC_RS_ALLOWED_AUDIENCES=
 
 It implements the resource server using `django-lasuite`, see the [documentation](https://github.com/suitenumerique/django-lasuite/blob/main/documentation/how-to-use-oidc-resource-server-backend.md)
 
+When `OIDC_RS_PRIVATE_KEY_STR` is set, the resource server publishes its public
+key on `/external_api/{version}/jwks`. This is the URI to declare to your OIDC
+provider. Do not confuse it with `/api/{version}/jwks`, which publishes the key
+validating the tokens Docs itself issues to call external services.
+
 ## Customise allowed routes
 
 Configure the `EXTERNAL_API` setting to control which routes and actions are available in the external API. Set it via the `EXTERNAL_API` environment variable (as JSON) or in Django settings.

documentation/system-requirements.md

@@ -89,7 +89,7 @@ Production deployments differ significantly from development environments. The t
 | --------- | --------------------- |
 | 3000      | Next.js               |
 | 8071      | Django                |
-| 4444      | Y-Provider            |
+| 3002      | yhub (collaboration WS) |
 | 8080      | Keycloak              |
 | 8083      | Nginx proxy           |
 | 9000/9001 | MinIO                 |

env.d/development/common

@@ -22,6 +22,11 @@ DJANGO_EMAIL_LOGO_IMG="http://localhost:3000/assets/logo-suite-numerique.png"
 DJANGO_EMAIL_PORT=1025
 DJANGO_EMAIL_URL_APP="http://localhost:3000"
 
+# JWT
+# The key itself is generated locally by "make generate-secret-keys", it is
+# never committed. A PEM does not fit in an env var, hence the _FILE variant.
+JWT_PRIVATE_KEY_FILE=/data/jwt/private.pem
+
 # Backend url
 IMPRESS_BASE_URL="http://localhost:8072"
 
@@ -72,12 +77,12 @@ OIDC_RS_ALLOWED_AUDIENCES=""
 USER_RECONCILIATION_FORM_URL=http://localhost:3000
 
 # Collaboration
-COLLABORATION_API_URL=http://y-provider-development:4444/collaboration/api/
+# TODO(yhub): no management API yet
 COLLABORATION_BACKEND_BASE_URL=http://app-dev:8000
 COLLABORATION_SERVER_ORIGIN=http://localhost:3000
 COLLABORATION_SERVER_SECRET=my-secret
 COLLABORATION_WS_NOT_CONNECTED_READ_ONLY=true
-COLLABORATION_WS_URL=ws://localhost:4444/collaboration/ws/
+COLLABORATION_WS_URL=ws://localhost:3002/ws/docs
 COLLABORATION_WS_INACTIVITY_TIMEOUT=15 # Seconds
 
 DJANGO_SERVER_TO_SERVER_API_TOKENS=server-api-token

env.d/development/common.e2e

@@ -1,6 +1,5 @@
 # For the CI job test-e2e
 BURST_THROTTLE_RATES="1000/minute"
-COLLABORATION_API_URL=http://y-provider:4444/collaboration/api/
 SUSTAINED_THROTTLE_RATES="1000/minute"
 Y_PROVIDER_API_BASE_URL=http://y-provider-converter:4444/api/