Manuel Raynaud
dcf139d039
All installation guides are updated to add the instructions about how to deploy docs with yhub.
3.5 KiB
Format conversion
Docs allows manipulating a document in multiple formats. You can export in HTML, copy as markdown, import markdown files, etc.
To make it work, some configuration should be made and another service enabled if you want to import files in docx format.
Conversion configuration
The first configuration to make is related to converting a docs in multiple format. This will be used by the formatted-content endpoint (/api/v1.0/documents/{document_id}/formatted-content/?content_format=(json|html|markdown)).
This service is also used by the create-for-owner endpoint and in the import of markdown file.
To configure it, use this environment variable in the Django service:
Y_PROVIDER_API_BASE_URL: http://{y-provider-service}:443/api/
For the Y_PROVIDER_API_BASE_URL, it can be the FQDN of your docs instance if you have configured a reverse proxy in front of the y-provider service and created a route to the /api for this service. It can also be the internal y-provider service url if Django can access it directly. In the case you deploy in a Kubernetes cluster, you can use the y-provider service url. We prefer the usage of internal url.
Requests to the y-provider service are authenticated with a short-lived admin JWT that Django signs itself (see core.services.jwt_services.JWTService), instead of a shared secret. The y-provider service verifies the signature against the public key Django publishes on its JWKS endpoint (/api/v1.0/jwks), so there is nothing to configure on the Django side beyond JWT_PRIVATE_KEY (see the JWT section of env.md).
On the y-provider side, point it at the Django backend so it can fetch the JWKS:
COLLABORATION_BACKEND_BASE_URL: http://{django-service}:8000
The JWKS is fetched from {COLLABORATION_BACKEND_BASE_URL}/api/v1.0/jwks, so that url has to be reachable from the y-provider service.
One service, not two anymore
The y-provider server used to serve the websockets as well, which is why it could be deployed twice — one release for the collaboration, one for the conversion (yProvider.converter). The collaboration is served by yhub now, so the conversion is all that is left: the y-provider service is the converter, and the yProvider.converter values are gone.
A deployment coming from a chart older than this one has one thing to change, the url the backend calls, which loses its suffix:
# before
Y_PROVIDER_API_BASE_URL: http://impress-docs-y-provider-converter:443/api/
# now
Y_PROVIDER_API_BASE_URL: http://impress-docs-y-provider:443/api/
Docspec configuration
Docspec is an external service made to transform legacy document formats into accessible, reusable content for modern editors. We are using it to import .docx file and convert them to be used with docs, enabling all the power of Docs without the caveats of this legacy format.
You are responsible to deploy your own version of docspec, if you are using our helm chart, deploying docspec is really easy, you just have to enable it in your values configuration:
docSpec:
enabled: true
If you deploy it your own way, be aware that this service exposes a public API, everybody knowing its url can use it. We highly suggest to deploy it in a private network, usable by docs.
Once docspec is deployed, you have to enable its usage in Django by using these environment variables:
CONVERSION_UPLOAD_ENABLED: True
DOCSPEC_API_URL: http://impress-docs-docspec:4000/conversion