Adapt recipe to Docs v6 (yhub collaboration server)

- the new yhub service needs new initialisation and RSA keys
- SOFT_MIGRATION on by default, add migrate_documents command
- back up the yhub database too
- document the v5 -> v6 upgrade in README and release/next

Following the [C4DT AI Policy](https://git.coopcloud.tech/c4dt/ai-policy/src/branch/main/AI-POLICY.md):

 #LLM_vibe
 #LLM_model Claude Opus 5.5

- [x] I take full responsibility for this code
- [x] I understand every line of this code
- [x] I tested this code thoroughly on my own computer / servers
- [x] None of the commit messages were created using LLMs
- [x] I will participate in any discussion on my own and will not use an LLM for the discussion
This commit is contained in:
Linus Gasser
2026-10-23 03:18:31 +00:00
committed by autonomic-bot
parent 32cc9b0190
commit 262bd5a02e
8 changed files with 168 additions and 21 deletions
+22
View File
@@ -19,6 +19,7 @@
## Quick start
* `abra app new lasuite-docs --secrets`
* Insert the two RSA keys, which abra cannot generate (see below)
* `abra app config <app-name>`
* `abra app deploy <app-name>`
@@ -27,6 +28,27 @@ You should then be able to visit the landing page of your app, but not yet to lo
* Migrations run automatically on backend startup. To trigger manually: `abra app cmd <app-name> backend migrate`
* Minio buckets are created automatically on first deploy. To manually trigger: `abra app cmd <app-name> minio minio_initialize`
## RSA keys
Since v6, the backend and the collaboration server (`yhub`) authenticate each other with signed tokens. Each needs its own RSA private key, never the same one:
```
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out jwt.pem
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out yhub-jwt.pem
abra app secret insert <app-name> jwt_pk v1 jwt.pem -f
abra app secret insert <app-name> yhub_jwt_pk v1 yhub-jwt.pem -f
rm jwt.pem yhub-jwt.pem
```
## Upgrading from v5 to v6
v6 replaces the collaboration server. Document content moves from the minio bucket to the new `yhub` service, which stores it in its own `yhub` database. If you skip the migration, every existing document opens **empty**. See [UPGRADE.md](https://github.com/suitenumerique/docs/blob/main/UPGRADE.md) upstream for details.
1. Insert the two RSA keys (see "RSA keys" above). The `collab_ss` secret is no longer used.
2. Leave `SOFT_MIGRATION` at its default (`true`) and deploy. The `yhub` schema is created on startup. A document is copied to yhub the first time someone opens it.
3. Copy all remaining documents: `abra app cmd <app-name> backend migrate_documents`. You can pass arguments, e.g. `abra app cmd <app-name> backend migrate_documents -- --dry-run`. Re-run it with `--retry-failed` if some documents failed.
4. Only after that, you may set `SOFT_MIGRATION=false`. Keep the minio bucket and its object versions: they hold the document history from before v6.
## Configure Authentication
lasuite-docs **requires** an OpenID Connect (OIDC) single sign-on provider; deployment has been tested with [Keycloak](https://git.coopcloud.tech/coop-cloud/keycloak), which we recommend, or you could also try [Authentik](https://git.coopcloud.tech/coop-cloud/authentik), both of which are installable using Co-op Cloud.