Collaboration

Table of Contents

Introduction
Default Values
Requirements
WOPI Configuration
Storing
Configuration
- Environment Variables
- YAML Example

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:

External document server
gateway service.
app provider 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 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

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.

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.

7.0.0

Environment variables for the collaboration service
Name	IV	Type	Default Value	Description
`COLLABORATION_APP_NAME`	6.0.0	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`	7.0.0	string	Collabora	The WebOffice app, either Collabora, OnlyOffice, Microsoft365 or MicrosoftOfficeOnline.
`COLLABORATION_APP_DESCRIPTION`	6.0.0	string	Open office documents with Collabora	App description
`COLLABORATION_APP_ICON`	6.0.0	string	image-edit	Icon for the app
`COLLABORATION_APP_ADDR`	6.0.0	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`	6.0.0	bool	false	Skip TLS certificate verification when connecting to the WOPI app
`COLLABORATION_APP_PROOF_DISABLE`	6.0.0	bool	false	Disable the proof keys verification
`COLLABORATION_APP_PROOF_DURATION`	6.0.0	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`	7.0.0	bool	false	Enable license checking to edit files. Needs to be enabled when using Microsoft365 with the business flow.
`OCIS_PERSISTENT_STORE` `COLLABORATION_STORE`	7.0.0	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`	7.0.0	[]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`	7.0.0	string	collaboration	The database name the configured store should use.
`COLLABORATION_STORE_TABLE`	7.0.0	string		The database table the store should use.
`OCIS_PERSISTENT_STORE_TTL` `COLLABORATION_STORE_TTL`	7.0.0	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`	7.0.0	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`	7.0.0	string		The password to authenticate with the store. Only applies when store type 'nats-js-kv' is configured.
`OCIS_JWT_SECRET` `COLLABORATION_JWT_SECRET`	pre5.0	string		The secret to mint and validate jwt tokens.
`COLLABORATION_GRPC_ADDR`	6.0.0	string	127.0.0.1:9301	The bind address of the GRPC service.
`OCIS_GRPC_PROTOCOL` `COLLABORATION_GRPC_PROTOCOL`	7.0.0	string	tcp	The transport protocol of the GRPC service.
`COLLABORATION_HTTP_ADDR`	6.0.0	string	127.0.0.1:9300	The bind address of the HTTP service.
`OCIS_HTTP_TLS_ENABLED`	pre5.0	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`	pre5.0	string		Path/File name of the TLS server certificate (in PEM format) for the http services.
`OCIS_HTTP_TLS_KEY`	pre5.0	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`	6.0.0	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`	6.0.0	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`	7.0.0	bool	false	Disable chat in the office web frontend. This feature applies to OnlyOffice and Microsoft.
`COLLABORATION_WOPI_PROXY_URL`	7.0.0	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`	7.0.0	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`	7.0.0	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`	6.0.0	string	com.owncloud.api.gateway	CS3 gateway used to look up user metadata.
`COLLABORATION_CS3API_DATAGATEWAY_INSECURE`	6.0.0	bool	false	Connect to the CS3API data gateway insecurely.
`OCIS_TRACING_ENABLED` `COLLABORATION_TRACING_ENABLED`	6.0.0	bool	false	Activates tracing.
`OCIS_TRACING_TYPE` `COLLABORATION_TRACING_TYPE`	6.0.0	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`	6.0.0	string		The endpoint of the tracing agent.
`OCIS_TRACING_COLLECTOR` `COLLABORATION_TRACING_COLLECTOR`	6.0.0	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`	6.0.0	string		The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.
`OCIS_LOG_PRETTY` `COLLABORATION_LOG_PRETTY`	6.0.0	bool	false	Activates pretty log output.
`OCIS_LOG_COLOR` `COLLABORATION_LOG_COLOR`	6.0.0	bool	false	Activates colorized log output.
`OCIS_LOG_FILE` `COLLABORATION_LOG_FILE`	6.0.0	string		The path to the log file. Activates logging to this file if set.
`COLLABORATION_DEBUG_ADDR`	6.0.0	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`	6.0.0	string		Token to secure the metrics endpoint.
`COLLABORATION_DEBUG_PPROF`	6.0.0	bool	false	Enables pprof, which can be used for profiling.
`COLLABORATION_DEBUG_ZPAGES`	6.0.0	bool	false	Enables zpages, which can be used for collecting and viewing in-memory traces.

YAML Example

Note the file shown below must be renamed and placed in the correct folder according to the Configuration File Naming conventions to be effective.
See the Notes for Environment Variables if you want to use environment variables in the yaml file.

7.0.0

# 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