Collaboration

Introduction

The collaboration service connects Infinite Scale with document servers such as Collabora, ONLYOFFICE or Microsoft using the WOPI protocol.

Since this service requires an external document server, it won’t start by default when using ocis server (supervised mode). You must start it manually with the ocis collaboration server command.

  • The collaboration service does not start automatically and must be started manually. For more details see the Start Infinite Scale section.

  • The reason for excluding the collaboration service from autostart is, that the service may need to be started multiple times but with own configs for each web office document server used.

Because the collaboration service needs to be started manually, the following prerequisite applies: On collaboration service startup, particular environment variables are required to be populated. If environment variables have a default like the MICRO_REGISTRY_ADDRESS, the default will be used, if not set otherwise. Use for all others the instance values as defined. If these environment variables are not provided or misconfigured, the collaboration service will not start up.

Required environment variables:

  • OCIS_URL

  • OCIS_JWT_SECRET

  • OCIS_REVA_GATEWAY

  • MICRO_REGISTRY_ADDRESS

Default Values

  • The collaboration service listens on port 9300 by default.

Requirements

The collaboration service requires the target document server (ONLYOFFICE, Collabora, etc.) to be up and running. Additionally, some Infinite Scale services are also required to be running in order to register the GRPC service for the open in app action in the webUI. The following internal and external services need to be available:

If any of the named services above have not been started or are not reachable, the collaboration service won’t start. Check with the List running services command if they have been started. If not, you must start them manually upfront before starting the collaboration service.

WOPI Configuration

There are a few variables that you need to set:

  • COLLABORATION_APP_NAME:
    The name of the connected WebOffice app, which can be one of the following:
    Collabora, OnlyOffice, Microsoft365 or MicrosoftOfficeOnline.

  • COLLABORATION_APP_ADDR:
    The URL of the collaborative editing app (onlyoffice, collabora, etc).
    For example: https://office.example.com.

  • COLLABORATION_APP_INSECURE:
    In case you are using a self signed certificate for the WOPI app you can tell the collaboration service to allow an insecure connection.

  • COLLABORATION_WOPI_SRC:
    The external address of the collaboration service. The target app (onlyoffice, collabora, etc) will use this address to read and write files from Infinite Scale.
    For example: https://wopi.example.com.

  • COLLABORATION_WOPI_SHORTTOKENS:
    Needs to be set if the office application like Microsoft Office Online complains about the URL is too long and refuses to work. If enabled, a store must be configured.

The rest of the configuration options available can be left with the default values.

Storing

The collaboration service can use a configured store via the global OCIS_PERSISTENT_STORE environment variable.

Note that for each global environment variable, an independent service-based one might be available additionally. For precedences see Environment Variable Notes. Check the configuration section below. Supported stores are:

Store Type Description

memory

Basic in-memory store. Will not survive a restart.
Usually the default for caches. See the store environment variable for which one is used.

nats-js-kv

Stores data using key-value-store feature of NATS JetStream.
Usually the default for stores, see the store environment variable for which one is used.

redis-sentinel

Stores data in a configured Redis Sentinel cluster.

noop

Stores nothing. Useful for testing. Not recommended in production environments.
The collaboration service can only be scaled if not using the memory store and the stores are configured identically over all instances!
If you have used one of the deprecated stores of a former version, you should reconfigure to use one of the supported ones as the deprecated stores will be removed in a later version.
Store specific notes

  • When using redis-sentinel:
    The Redis master to use is configured via e.g. OCIS_PERSISTENT_STORE_NODES in the form of <sentinel-host>:<sentinel-port>/<redis-master> like 10.10.0.200:26379/mymaster.

  • When using nats-js-kv:

    • It is recommended to set OCIS_PERSISTENT_STORE_NODES to the same value as OCIS_EVENTS_ENDPOINT. That way the cache uses the same nats instance as the event bus. See the Event Bus Configuration for more details.

    • Authentication can be added, if configured, via OCIS_CACHE_AUTH_USERNAME and OCIS_CACHE_AUTH_PASSWORD.

    • It is possible to set OCIS_CACHE_DISABLE_PERSISTENCE to instruct nats to not persist cache data on disc.

Note that the collaboration service does not use the event bus, but other services like the userlog service do.

Configuration

Environment Variables

The collaboration service is configured via the following environment variables. Read the Environment Variable Types documentation for important details. Column IV shows with which release the environment variable has been introduced.

404: Not Found

  • 8.1.0

404: Not Found

YAML Example

  • 8.1.0

404: Not Found