Since CodiMD is not built upon the WOPI Protocol (as it happens with Collabora Code), an additional component needs to be deployed alongside the WOPI Server to fill this gap between the application provider and the application itself.
Bridging that gap will be the job for the WOPI Bridge: a sidecar container to translate CodiMD API calls into file operations and vice-versa.
A small configuration patch needs to be applied to an IOP deployment to enable this new component and plug it into the WOPI Server application providers. The main parameters to configure being:
CODIMD_INT_URLconnects the bridge and the CodiMD service running inside the cluster.
CODIMD_EXT_URLwill be used to generate the URL presented to the end-user when
open-file-in-app-provideris called in reva.
wopiserver: config: appProviders: wopibridgeurl: https://<hostname.domain.tld>/wopib wopibridge: enabled: true env: APP_ROOT: /wopib CODIMD_EXT_URL: https://<hostname.domain.tld>/codimd CODIMD_INT_URL: http://meshapps-codimd ingress: enabled: true annotations: kubernetes.io/ingress.class: nginx nginx.ingress.kubernetes.io/ssl-redirect: "true" hostname: <hostname.domain.tld> path: /wopib
Note: depending on the ingress controller path-matching policies, you might experience routing issues between requests addressed to the WOPI Server and the Bridge (as their
path-s can collide). Review your controller’s path priority policies and use an alternative path in case that could be an issue.
Refer to the chart’s documentation for a complete reference of all the configuration options available. Once ready, the release can be patched with the following command:
helm upgrade -i iop sciencemesh/iop --reuse-values -f wopibridge.yaml
To deploy the application, the
sciencemesh/meshapps umbrella chart already provides a handful of defaults for a lightweight and “stateless” CodiMD installation:
codimdcontainer image (
gitlab-registry.cern.ch/authoring/notes/codimd:cernbox-integration) with some extra features to enable this workflow.
The only key aspects left for the user to configure are:
CMD_SAVE_WEBHOOKenv. variable: pointing to the
/saveendpoint of the WOPI Bridge, that will be called when a document is closed.
Note: this webhook needs to be served over HTTPS to work with CodiMD, hence the need to use its external FQDN.
CMD_URL_PATHand an ingress rewrite annotation to strip the base URL (
/codimd) from external requests.
postgresql.postgresqlPasswordto protect the database that will be used as a temporary cache for the notes.
Note: alternatively, MariaDB can be used instead of PostgreSQL when deploying CodiMD. Refer to the chart’s parameters for all the options available.
Here’s an example
codimd.yaml combining all these:
codimd: enabled: true codimd: connection: domain: <hostname.domain.tld> protocolUseSSL: true extraEnvironmentVariables: CMD_SAVE_WEBHOOK: https://<hostname.domain.tld>/wopib/save CMD_URL_PATH: codimd postgresql: postgresqlPassword: <password> ingress: annotations: kubernetes.io/ingress.class: nginx nginx.ingress.kubernetes.io/rewrite-target: /$2 nginx.ingress.kubernetes.io/ssl-redirect: "true" enabled: true hosts: - host: <hostname.domain.tld> paths: - /codimd(/|$)(.*)
After this file is defined, it’s just a matter of upgrading the chart while reusing any previous values, as follows:
helm upgrade -i meshapps sciencemesh/meshapps --reuse-values -f codimd.yaml
There are three extra steps left for the IOP to integrate with this application. These will require modifying the Revad configuration to identify the files that will be opened by CodiMD:
appregistryservice running on the gateway to identify these files:
[grpc.services.appregistry.static.rules] "text/markdown" = "iop-gateway:19000" "application/compressed-markdown" = "iop-gateway:19000"
wopibridgeURL might be inserted as part of the
appprovidersettings on the gateway; to generate a shorter and user-friendlier URL when opening from the reva cli.
[grpc.services.appprovider] wopibridgeurl = "https://<hostname.domain.tld>/wopib"
.zmdfile extension, used to package markdown files together with uploaded images, and the
application/compressed-markdownMIME-type used to identify these files. This needs to be done on all the running
storageproviderservices: whether using a standalone deployment or one based on multiple, decoupled storage providers.
[grpc.services.storageprovider.mimetypes] ".zmd" = "application/compressed-markdown"