97 lines
4.9 KiB
Markdown
97 lines
4.9 KiB
Markdown
# lasuite-docs
|
|
|
|
> [Docs](https://docs.numerique.gouv.fr/home/) (part of [La Suite Numerique](https://lasuite.numerique.gouv.fr/en)) for Co-op Cloud
|
|
|
|
<!-- metadata -->
|
|
|
|
* **Maintainer**: [@trav](https://git.coopcloud.tech/trav), [@notplants](https://git.coopcloud.tech/notplants), [@ineiti](https://git.coopcloud.tech/ineiti)
|
|
* **Category**: Apps
|
|
* **Status**: 2
|
|
* **Image**: [`lasuite/docs`](https://hub.docker.com/r/lasuite/docs), 4, upstream
|
|
* **Healthcheck**: No
|
|
* **Backups**: No
|
|
* **Email**: 3
|
|
* **Tests**: No
|
|
* **SSO**: 3
|
|
|
|
<!-- endmetadata -->
|
|
|
|
## Quick start
|
|
|
|
* `abra app new lasuite-docs --secrets`
|
|
* `abra app config <app-name>`
|
|
* `abra app deploy <app-name>`
|
|
|
|
You should then be able to visit the landing page of your app, but not yet to login. To login, you need to deploy and integrate single sign on (described below in the "Configure Authentication" section).
|
|
|
|
* 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. The recipe generates both automatically on first deploy into the `jwt_keys` volume (the `jwt-keys` service, using the yhub image's Node crypto) and reuses them on later deploys. They are not Swarm secrets because abra cannot generate PEM keys and Swarm secrets must exist before the stack is deployed.
|
|
|
|
## 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. The `collab_ss` secret is no longer used. The two RSA keys are generated automatically on first deploy (see "RSA keys" above).
|
|
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.
|
|
|
|
Instructions for integrating keycloak with docs after deploying it, are below.
|
|
|
|
* In keycloak, create a realm (save the name of this realm, you will need it later)
|
|
* Within that realm, create a client
|
|
* during client creation, ensure:
|
|
- Standard flow: True
|
|
- Direct access grants: True
|
|
- Authorization: True
|
|
- Client authentication: True
|
|
- PKCE method: none
|
|
* Within the client tab, for your client, click on "Credentials". Click on the the copy button to copy "Client Secret" so you can insert this into your coop cloud deployment in the next step.
|
|
* `abra app secret insert <app-name> oidc_rpcs v2 <yoursecret>`
|
|
* `abra app config <app-name>` # set SECRET_OIDC_RPCS_VERSION=v2
|
|
|
|
* Now create a user for this client within keycloak. Within the Users tab, click "Add User". Any username and password works. Save this info.
|
|
|
|
You then additionally need to modify the config of docs to point to your keycloak deployment.
|
|
|
|
* `abra app config <app-name>`
|
|
```
|
|
OIDC_REALM=<the realm you configured in keycloak>
|
|
AUTH_DOMAIN=<the domain of your keycloak instance>
|
|
OIDC_RP_CLIENT_ID=<yourkeycloakclientid>
|
|
```
|
|
|
|
then redeploy docs:
|
|
`abra app deploy <app-name> --force`
|
|
|
|
at this point, when you go to your docs url, you shoud then be able to click "login" and login with the username and password for the user you created in keycloak.
|
|
|
|
you can make additional users in keycloak for this "client" and they will all be able to login to docs and collaborate.
|
|
|
|
## Configure E-Mail
|
|
|
|
Using `abra app config <app-name>` you need to set the following for your smtp server:
|
|
|
|
```
|
|
DJANGO_EMAIL_HOST="yourmailserver.com"
|
|
DJANGO_EMAIL_PORT=1025
|
|
DJANGO_EMAIL_FROM=noreply@example.com
|
|
```
|
|
|
|
You then need to insert the password for your smtp server as a secret:
|
|
|
|
* `abra app secret insert <app-name> email_pass v2 <youremailpass>`
|
|
* `abra app config <app-name>` # set SECRET_EMAIL_PASS_VERSION=v2
|
|
|
|
Then redeploy the app, and automated e-mail sending should work:
|
|
|
|
`abra app deploy <app-name> --force`
|