Collaboration

Abstract

The collaboration service connects ocis 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. You must start it manually with the ocis collaboration server command.

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

Requirements
WOPI Configuration
Storing
Example Yaml Config

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:

External document server.
The gateway service.
The app-registry service.

If any of the named services above have not been started or are not reachable, the collaboration service won’t start. For the binary or the docker release of Infinite Scale, check with the ocis list 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 app which is shown to the user. You can chose freely but you are limited to a single word without special characters or whitespaces. We recommend to use pascalCase like ‘CollaboraOnline’.
COLLABORATION_APP_PRODUCT:
The product name of the connected WebOffice app, which can be one of the following:
Collabora, OnlyOffice, Microsoft365 or MicrosoftOfficeOnline. This is used to internally control the behavior according to the different features of the used products.
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 (which contains the access token) and refuses to work. If enabled, a store must be configured.

The application can be customized further by changing the COLLABORATION_APP_* options to better describe the application.

Storing

The collaboration service persists information via the configured store in COLLABORATION_STORE. Possible stores are:

memory: Basic in-memory store. Will not survive a restart. This is not recommended for this service.
redis-sentinel: Stores data in a configured Redis Sentinel cluster.
nats-js-kv: Stores data using key-value-store feature of nats jetstream. This is the default value.
noop: Stores nothing. Useful for testing. Not recommended in production environments.

Other store types may work but are not supported currently.

Note: The service can only be scaled if not using memory store and the stores are configured identically over all instances!

Note that if you have used one of the deprecated stores, you should reconfigure to 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_CACHE_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_CACHE_STORE_NODES to the same value as OCIS_EVENTS_ENDPOINT. That way the cache uses the same nats instance as the event bus.
When using the nats-js-kv store, it is possible to set OCIS_CACHE_DISABLE_PERSISTENCE to instruct nats to not persist cache data on disc.

Example Yaml Config

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62


# Autogenerated
# Filename: collaboration-config-example.yaml

app:
  name: Collabora
  product: Collabora
  description: Open office documents with Collabora
  icon: image-edit
  addr: https://127.0.0.1:9980
  insecure: false
  proofkeys:
    disable: false
    duration: 12h
  licensecheckenable: false
store:
  store: nats-js-kv
  nodes:
  - 127.0.0.1:9233
  database: collaboration
  table: ""
  ttl: 30m0s
  username: ""
  password: ""
token_manager:
  jwt_secret: ""
grpc:
  addr: 127.0.0.1:9301
  protocol: tcp
http:
  addr: 127.0.0.1:9300
  tls:
    enabled: false
    cert: ""
    key: ""
wopi:
  wopisrc: https://localhost:9300
  secret: ""
  disable_chat: false
  proxy_url: ""
  proxy_secret: ""
  short_tokens: false
cs3api:
  gateway:
    name: com.owncloud.api.gateway
  datagateway:
    insecure: false
  grpc_client_tls: null
tracing:
  enabled: false
  type: ""
  endpoint: ""
  collector: ""
log:
  level: ""
  pretty: false
  color: false
  file: ""
debug:
  addr: 127.0.0.1:9304
  token: ""
  pprof: false
  zpages: false

Environment Variables

Name	Type	Default Value	Description
COLLABORATION_APP_NAME	string	Collabora	The name of the app which is shown to the user. You can chose freely but you are limited to a single word without special characters or whitespaces. We recommend to use pascalCase like ‘CollaboraOnline’.
COLLABORATION_APP_PRODUCT	string	Collabora	The WebOffice app, either Collabora, OnlyOffice, Microsoft365 or MicrosoftOfficeOnline.
COLLABORATION_APP_DESCRIPTION	string	Open office documents with Collabora	App description
COLLABORATION_APP_ICON	string	image-edit	Icon for the app
COLLABORATION_APP_ADDR	string	https://127.0.0.1:9980	The URL where the WOPI app is located, such as https://127.0.0.1:8080.
COLLABORATION_APP_INSECURE	bool	false	Skip TLS certificate verification when connecting to the WOPI app
COLLABORATION_APP_PROOF_DISABLE	bool	false	Disable the proof keys verification
COLLABORATION_APP_PROOF_DURATION	string	12h	Duration for the proof keys to be cached in memory, using time.ParseDuration format. If the duration can’t be parsed, we’ll use the default 12h as duration
COLLABORATION_APP_LICENSE_CHECK_ENABLE	bool	false	Enable license checking to edit files. Needs to be enabled when using Microsoft365 with the business flow.
OCIS_PERSISTENT_STORE COLLABORATION_STORE	string	nats-js-kv	The type of the store. Supported values are: ‘memory’, ’nats-js-kv’, ‘redis-sentinel’, ’noop’. See the text description for details.
OCIS_PERSISTENT_STORE_NODES COLLABORATION_STORE_NODES	[]string	[127.0.0.1:9233]	A list of nodes to access the configured store. This has no effect when ‘memory’ store is configured. Note that the behaviour how nodes are used is dependent on the library of the configured store. See the Environment Variable Types description for more details.
COLLABORATION_STORE_DATABASE	string	collaboration	The database name the configured store should use.
COLLABORATION_STORE_TABLE	string		The database table the store should use.
OCIS_PERSISTENT_STORE_TTL COLLABORATION_STORE_TTL	Duration	30m0s	Time to live for events in the store. Defaults to ‘30m’ (30 minutes). See the Environment Variable Types description for more details.
OCIS_PERSISTENT_STORE_AUTH_USERNAME COLLABORATION_STORE_AUTH_USERNAME	string		The username to authenticate with the store. Only applies when store type ’nats-js-kv’ is configured.
OCIS_PERSISTENT_STORE_AUTH_PASSWORD COLLABORATION_STORE_AUTH_PASSWORD	string		The password to authenticate with the store. Only applies when store type ’nats-js-kv’ is configured.
OCIS_JWT_SECRET COLLABORATION_JWT_SECRET	string		The secret to mint and validate jwt tokens.
COLLABORATION_GRPC_ADDR	string	127.0.0.1:9301	The bind address of the GRPC service.
OCIS_GRPC_PROTOCOL COLLABORATION_GRPC_PROTOCOL	string	tcp	The transport protocol of the GRPC service.
COLLABORATION_HTTP_ADDR	string	127.0.0.1:9300	The bind address of the HTTP service.
OCIS_HTTP_TLS_ENABLED	bool	false	Activates TLS for the http based services using the server certifcate and key configured via OCIS_HTTP_TLS_CERTIFICATE and OCIS_HTTP_TLS_KEY. If OCIS_HTTP_TLS_CERTIFICATE is not set a temporary server certificate is generated - to be used with PROXY_INSECURE_BACKEND=true.
OCIS_HTTP_TLS_CERTIFICATE	string		Path/File name of the TLS server certificate (in PEM format) for the http services.
OCIS_HTTP_TLS_KEY	string		Path/File name for the TLS certificate key (in PEM format) for the server certificate to use for the http services.
COLLABORATION_WOPI_SRC	string	https://localhost:9300	The WOPI source base URL containing schema, host and port. Set this to the schema and domain where the collaboration service is reachable for the wopi app, such as https://office.owncloud.test.
COLLABORATION_WOPI_SECRET	string		Used to mint and verify WOPI JWT tokens and encrypt and decrypt the REVA JWT token embedded in the WOPI JWT token.
COLLABORATION_WOPI_DISABLE_CHAT OCIS_WOPI_DISABLE_CHAT	bool	false	Disable chat in the office web frontend. This feature applies to OnlyOffice and Microsoft.
COLLABORATION_WOPI_PROXY_URL	string		The URL to the ownCloud Office365 WOPI proxy. Optional. To use this feature, you need an office365 proxy subscription. If you become part of the Microsoft CSP program (https://learn.microsoft.com/en-us/partner-center/enroll/csp-overview), you can use WebOffice without a proxy.
COLLABORATION_WOPI_PROXY_SECRET	string		Optional, the secret to authenticate against the ownCloud Office365 WOPI proxy. This secret can be obtained from ownCloud via the office365 proxy subscription.
COLLABORATION_WOPI_SHORTTOKENS	bool	false	Use short access tokens for WOPI access. This is useful for office packages, like Microsoft Office Online, which have URL length restrictions. If enabled, a persistent store must be configured.
OCIS_REVA_GATEWAY	string	com.owncloud.api.gateway	CS3 gateway used to look up user metadata.
COLLABORATION_CS3API_DATAGATEWAY_INSECURE	bool	false	Connect to the CS3API data gateway insecurely.
OCIS_TRACING_ENABLED COLLABORATION_TRACING_ENABLED	bool	false	Activates tracing.
OCIS_TRACING_TYPE COLLABORATION_TRACING_TYPE	string		The type of tracing. Defaults to ‘’, which is the same as ‘jaeger’. Allowed tracing types are ‘jaeger’ and ’’ as of now.
OCIS_TRACING_ENDPOINT COLLABORATION_TRACING_ENDPOINT	string		The endpoint of the tracing agent.
OCIS_TRACING_COLLECTOR COLLABORATION_TRACING_COLLECTOR	string		The HTTP endpoint for sending spans directly to a collector, i.e. http://jaeger-collector:14268/api/traces. Only used if the tracing endpoint is unset.
OCIS_LOG_LEVEL COLLABORATION_LOG_LEVEL	string		The log level. Valid values are: ‘panic’, ‘fatal’, ’error’, ‘warn’, ‘info’, ‘debug’, ’trace’.
OCIS_LOG_PRETTY COLLABORATION_LOG_PRETTY	bool	false	Activates pretty log output.
OCIS_LOG_COLOR COLLABORATION_LOG_COLOR	bool	false	Activates colorized log output.
OCIS_LOG_FILE COLLABORATION_LOG_FILE	string		The path to the log file. Activates logging to this file if set.
COLLABORATION_DEBUG_ADDR	string	127.0.0.1:9304	Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.
COLLABORATION_DEBUG_TOKEN	string		Token to secure the metrics endpoint.
COLLABORATION_DEBUG_PPROF	bool	false	Enables pprof, which can be used for profiling.
COLLABORATION_DEBUG_ZPAGES	bool	false	Enables zpages, which can be used for collecting and viewing in-memory traces.