lasuite-docs/UPGRADE.md

Upgrade

All instructions to upgrade this project from one release to the next will be documented in this file. Upgrades must be run sequentially, meaning you should not skip minor/major releases while upgrading (fix releases can be skipped).

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

For most upgrades, you just need to run the django migrations with the following command inside your docker container:

python manage.py migrate

(Note : in your development environment, you can make migrate.)

[Unreleased]

• The endpoint /api/v1.0/documents/{document_id}/content/, added in 5.0.0, is removed, both its GET and its PATCH. The content of a document is now saved and served by the collaboration server, the editor exchanging it over the websocket, so nothing reads or writes it through the API anymore. If you integrate with Docs, stop calling this endpoint: the content_patch and content_retrieve abilities disappear from the document payload along with it. /api/v1.0/documents/{document_id}/formatted-content/ is not affected. The CONTENT_METADATA_CACHE_TIMEOUT setting only tuned the cache of the removed GET and is no longer read, you can drop it from your configuration.

• 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.

• ⚠️ The collaboration server now calls the backend on its own, to declare that a document was edited, and signs those calls: it needs an RSA private key of its own, which it had not before. Generate one and give it to the collaboration server in YHUB_JWT_PRIVATE_KEY, or in a file YHUB_JWT_PRIVATE_KEY_FILE points at:

  openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out yhub-private.pem
  

  There is nothing to configure on the backend side: it reads the public half from the JWKS the collaboration server publishes on /collaboration/jwks/v1, which it fetches over YHUB_API_BASE_URL — so the two only need to reach each other, and this key can be rolled without the backend being touched. Do not share the backend key (JWT_PRIVATE_KEY) with it: each service signs with a key of its own.

  Without this key the collaboration server keeps serving documents, and warns at startup that it will not notify the backend: the updated_at of a document then stops following the edits made in the editor, and the lists ordered by it drift out of date. In a development environment, make generate-secret-keys creates the key in data/jwt/.

[5.0.0] - 2026-04-30

We made several changes around document content management leading to several breaking changes in the API.

• The endpoint /api/v1.0/documents/{document_id}/content/ has been renamed in /api/v1.0/documents/{document_id}/formatted-content/
• There is no more content attribute in the response of /api/v1.0/documents/{document_id}/, two new endpoints have been added to retrieve or update the document content.
• A new GET /api/v1.0/documents/{document_id}/content/ endpoint has been implemented to fetch the document content ; this endpoint streams the whole content with a text/plain content-type response.
• A new PATCH /api/v1.0/documents/{document_id}/content/ endpoint has been added to update the document content ; expected payload is:

{
  "content": "document content in base64",
}

Other changes:

• The deprecated endpoint /api/v1.0/documents/<document_id>/descendants is removed. The search endpoint should be used instead.
• Upgrade docspec dependency to version >= 3.0.0 The docspec service has changed since version 3.0.0, we ware now compatible with this version and not with version 2.x.x anymore
• It is now possible to use the Mistral SDK instead of the OpenAI for the AI features. If your provider is compatible with the mistral API, we encourage you to use it.
• AI_API_KEY settings is renamed in OPENAI_SDK_API_KEY and is only used to congiure the OpenAi sdk
• AI_BASE_URL settings is renamed in OPENAI_SDK_BASE_URL and is only used to congiure the OpenAi sdk

[4.6.0] - 2026-02-27

• ⚠️ Some setup have changed to offer a bigger flexibility and consistency, overriding the favicon and logo are now from the theme configuration. https://github.com/suitenumerique/docs/blob/f24b047a7cc146411412bf759b5b5248a45c3d99/src/backend/impress/configuration/theme/default.json#L129-L161

[4.0.0] - 2025-11-26

• ⚠️ We updated @gouvfr-lasuite/ui-kit to 0.18.0, so if you are customizing Docs with a css layer or with a custom template, you need to update your customization to follow the new design system structure.
  More information about the changes in the design system can be found here:

  • https://suitenumerique.github.io/cunningham/storybook/?path=/docs/migrating-from-v3-to-v4--docs
  • https://github.com/suitenumerique/docs/pull/1605
  • https://github.com/suitenumerique/docs/blob/main/docs/theming.md

• If you were using the THEME_CUSTOMIZATION_FILE_PATH and have overridden the header logo, you need to update your customization file to follow the new structure of the header, it is now:

  {
    ...,
    "header": {
      "icon": {
        "src": "your_logo_src",
        "width": "your_logo_width",
        "height": "your_logo_height"
      }
    }
  }
  

[3.3.0] - 2025-05-22

⚠️ For some advanced features (ex: Export as PDF) Docs relies on XL packages from BlockNote. These are licenced under AGPL-3.0 and are not MIT compatible. You can perfectly use Docs without these packages by setting the environment variable PUBLISH_AS_MIT to true. That way you'll build an image of the application without the features that are not MIT compatible. Read the environment variables documentation for more information.

The footer is now configurable from a customization file. To override the default one, you can use the THEME_CUSTOMIZATION_FILE_PATH environment variable to point to your customization file. The customization file must be a JSON file and must follow the rules described in the theming documentation.

[3.0.0] - 2025-03-28

We are not using the nginx auth request anymore to access the collaboration server (yProvider) The authentication is now managed directly from the yProvider server. You must remove the annotation nginx.ingress.kubernetes.io/auth-url from the ingressCollaborationWS.

This means as well that the yProvider server must be able to access the Django server. To do so, you must set the COLLABORATION_BACKEND_BASE_URL environment variable to the yProvider service.

[2.2.0] - 2025-02-10

• AI features are now limited to users who are authenticated. Before this release, even anonymous users who gained editor access on a document with link reach used to get AI feature. If you want anonymous users to keep access on AI features, you must now define the AI_ALLOW_REACH_FROM setting to "public".