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.
|
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
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
orMicrosoftOfficeOnline
. -
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_APP_WOPISRC
:
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
.
The rest of the configuration options available can be left with the default values.
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.
Deprecation Info | Deprecation Version | Removal Version | Deprecation Replacement |
---|---|---|---|
COLLABORATION_CS3API_GATEWAY_NAME removed for simplicity. |
6.0 |
next-prod |
Name | IV | Type | Default Value | Description |
---|---|---|---|---|
|
6.0.0 |
string |
Collabora |
The name of the app, either Collabora, OnlyOffice, Microsoft365 or MicrosoftOfficeOnline |
|
6.0.0 |
string |
Open office documents with Collabora |
App description |
|
6.0.0 |
string |
image-edit |
Icon for the app |
|
6.0.0 |
string |
com.github.owncloud.collaboration |
Name for the app lock |
|
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. |
|
6.0.0 |
bool |
false |
Skip TLS certificate verification when connecting to the WOPI app |
|
6.0.0 |
bool |
false |
Disable the proof keys verification |
|
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 |
|
next |
bool |
false |
Enable license checking to edit files. Needs to be enabled when using Microsoft365 with the business flow. |
|
pre5.0 |
string |
|
The secret to mint and validate jwt tokens. |
|
6.0.0 |
string |
127.0.0.1:9301 |
The bind address of the GRPC service. |
|
next |
string |
tcp |
The transport protocol of the GRPC service. |
|
6.0.0 |
string |
127.0.0.1:9300 |
The bind address of the HTTP service. |
|
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. |
|
pre5.0 |
string |
|
Path/File name of the TLS server certificate (in PEM format) for the http services. |
|
pre5.0 |
string |
|
Path/File name for the TLS certificate key (in PEM format) for the server certificate to use for the http services. |
|
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. |
|
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. |
|
next |
bool |
false |
Disable chat in the office web frontend. This feature applies to OnlyOffice and Microsoft. |
|
next |
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. |
|
next |
string |
|
Optional, the secret to authenticate against the ownCloud Office365 WOPI proxy. This secret can be obtained from ownCloud via the office365 proxy subscription. |
|
6.0.0 |
string |
com.owncloud.api.gateway |
CS3 gateway used to look up user metadata. |
|
6.0.0 |
bool |
false |
Connect to the CS3API data gateway insecurely. |
|
6.0.0 |
bool |
false |
Activates tracing. |
|
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. |
|
6.0.0 |
string |
|
The endpoint of the tracing agent. |
|
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. |
|
6.0.0 |
string |
|
The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'. |
|
6.0.0 |
bool |
false |
Activates pretty log output. |
|
6.0.0 |
bool |
false |
Activates colorized log output. |
|
6.0.0 |
string |
|
The path to the log file. Activates logging to this file if set. |
|
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. |
|
6.0.0 |
string |
|
Token to secure the metrics endpoint. |
|
6.0.0 |
bool |
false |
Enables pprof, which can be used for profiling. |
|
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.
# Autogenerated
# Filename: collaboration-config-example.yaml
app:
name: Collabora
description: Open office documents with Collabora
icon: image-edit
lockname: com.github.owncloud.collaboration
addr: https://127.0.0.1:9980
insecure: false
proofkeys:
disable: false
duration: 12h
licensecheckenable: false
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: ""
cs3api:
gateway:
name: com.owncloud.api.gateway
datagateway:
insecure: false
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