diff --git a/docs/services/general-info/port-ranges.md b/docs/services/general-info/port-ranges.md
index 317fa8b87..c51fadb68 100644
--- a/docs/services/general-info/port-ranges.md
+++ b/docs/services/general-info/port-ranges.md
@@ -71,7 +71,7 @@ We also suggest to use the last port in your extensions' range as a debug/metric
 | 9285-9289  | FREE                                                                                   |
 | 9290-9294  | FREE                                                                                   |
 | 9295-9299  | FREE                                                                                   |
-| 9300-9304  | FREE                                                                                   |
+| 9300-9304  | [collaboration]({{< ref "../collaboration/_index.md" >}})                              |
 | 9305-9309  | FREE                                                                                   |
 | 9310-9314  | FREE                                                                                   |
 | 9315-9319  | FREE                                                                                   |
diff --git a/services/collaboration/README.md b/services/collaboration/README.md
new file mode 100644
index 000000000..d7dce5a99
--- /dev/null
+++ b/services/collaboration/README.md
@@ -0,0 +1,22 @@
+# Collaboration
+
+The collaboration service connects ocis with document servers such as collabora and onlyoffice using the WOPI protocol.
+
+Since this service requires an external service (onlyoffice, for example), it won't run by default with the general `ocis server` command. You need to run it manually with the `ocis collaboration server` command.
+
+## Requirements
+
+The collaboration service requires the target document server (onlyoffice, collabora, etc) to be up and running.
+We also need reva's gateway and app provider services to be running in order to register the GRPC service for the "open in app" action.
+
+If any of those services are down, the collaboration service won't start.
+
+## Configuration
+
+There are a few variables that you need to set:
+
+* `COLLABORATION_WOPIAPP_ADDR`: The URL of the WOPI app (onlyoffice, collabora, etc). For example: "https://office.mycloud.prv".
+* `COLLABORATION_HTTP_ADDR`: The external address of the collaboration service. The target app (onlyoffice, collabora) will use this address to read and write files from ocis. For example: "wopiserver.mycloud.prv"
+* `COLLABORATION_HTTP_SCHEME`: The scheme to be used when accessing the collaboration service. Either "http" or "https". This will be used to build the URL that the WOPI app needs in order to contact this service.
+
+The rest of the configuration options available can be left with the default values.
diff --git a/services/collaboration/pkg/config/config.go b/services/collaboration/pkg/config/config.go
index 117dd9fe1..f0afb149f 100644
--- a/services/collaboration/pkg/config/config.go
+++ b/services/collaboration/pkg/config/config.go
@@ -14,7 +14,7 @@ type Config struct {
 	Service Service `yaml:"-"`
 	App     App     `yaml:"app"`
 
-	Secret string `yaml:"secret" env:"COLLABORATION_SECRET" desc:"Used as JWT token and to encrypt access token."`
+	JWTSecret string `yaml:"jwt_secret" env:"OCIS_JWT_SECRET;COLLABORATION_JWT_SECRET" desc:"Used as JWT token and to encrypt access token."`
 
 	GRPC    GRPC    `yaml:"grpc"`
 	HTTP    HTTP    `yaml:"http"`
@@ -23,7 +23,7 @@ type Config struct {
 
 	Tracing *Tracing `yaml:"tracing"`
 	Log     *Log     `yaml:"log"`
-	Debug   Debug    `yaml:"debug"`
+	//Debug   Debug    `yaml:"debug"`
 
 	Context context.Context `yaml:"-"`
 }
diff --git a/services/collaboration/pkg/config/cs3api.go b/services/collaboration/pkg/config/cs3api.go
index d810e8ca2..3ea45b3c3 100644
--- a/services/collaboration/pkg/config/cs3api.go
+++ b/services/collaboration/pkg/config/cs3api.go
@@ -7,9 +7,9 @@ type CS3Api struct {
 }
 
 type Gateway struct {
-	Name string `yaml: "name" env:"COLLABORATION_CS3API_GATEWAY_NAME" desc:"service name of the CS3API gateway"`
+	Name string `yaml: "name" env:"COLLABORATION_CS3API_GATEWAY_NAME" desc:"The service name of the CS3API gateway."`
 }
 
 type DataGateway struct {
-	Insecure bool `yaml:"insecure" env:"COLLABORATION_CS3API_DATAGATEWAY_INSECURE" desc:"connect to the CS3API data gateway insecurely"`
+	Insecure bool `yaml:"insecure" env:"COLLABORATION_CS3API_DATAGATEWAY_INSECURE" desc:"Connect to the CS3API data gateway insecurely."`
 }
diff --git a/services/collaboration/pkg/config/defaults/defaultconfig.go b/services/collaboration/pkg/config/defaults/defaultconfig.go
index 7025860fc..05cfe3893 100644
--- a/services/collaboration/pkg/config/defaults/defaultconfig.go
+++ b/services/collaboration/pkg/config/defaults/defaultconfig.go
@@ -25,26 +25,27 @@ func DefaultConfig() *config.Config {
 			Icon:        "image-edit",
 			LockName:    "com.github.owncloud.collaboration",
 		},
-		Secret: uniuri.NewLen(32),
+		JWTSecret: uniuri.NewLen(32),
 		GRPC: config.GRPC{
-			Addr:      "127.0.0.1:56778",
+			Addr:      "0.0.0.0:9301",
 			Namespace: "com.owncloud.collaboration",
 		},
 		HTTP: config.HTTP{
-			Addr:      "127.0.0.1:6789",
+			Addr:      "127.0.0.1:9300",
+			BindAddr:  "0.0.0.0:9300",
 			Namespace: "com.owncloud.collaboration",
-			//Scheme: "http",
+			Scheme:    "https",
 		},
 		WopiApp: config.WopiApp{
 			Addr:     "https://127.0.0.1:8080",
-			Insecure: true, // TODO: this should have a secure default
+			Insecure: false,
 		},
 		CS3Api: config.CS3Api{
 			Gateway: config.Gateway{
 				Name: "com.owncloud.api.gateway",
 			},
 			DataGateway: config.DataGateway{
-				Insecure: true, // TODO: this should have a secure default
+				Insecure: false,
 			},
 		},
 	}
diff --git a/services/collaboration/pkg/config/http.go b/services/collaboration/pkg/config/http.go
index e2b472a9c..5b95cd017 100644
--- a/services/collaboration/pkg/config/http.go
+++ b/services/collaboration/pkg/config/http.go
@@ -6,7 +6,7 @@ import (
 
 // HTTP defines the available http configuration.
 type HTTP struct {
-	Addr      string                `yaml:"addr" env:"COLLABORATION_HTTP_ADDR" desc:"The address of the HTTP service."`
+	Addr      string                `yaml:"addr" env:"COLLABORATION_HTTP_ADDR" desc:"The external address of the HTTP service. Either IP address or host (127.0.0.1:9301 or wopi.private.prv). The configured "Scheme" will be used to build public URLs along with this address."`
 	BindAddr  string                `yaml:"bindaddr" env:"COLLABORATION_HTTP_BINDADDR" desc:"The bind address of the HTTP service."`
 	Namespace string                `yaml:"-"`
 	Scheme    string                `yaml:"scheme" env:"COLLABORATION_HTTP_SCHEME" desc:"Either http or https"`
diff --git a/services/collaboration/pkg/config/wopiapp.go b/services/collaboration/pkg/config/wopiapp.go
index fcf24ca6e..33784ce95 100644
--- a/services/collaboration/pkg/config/wopiapp.go
+++ b/services/collaboration/pkg/config/wopiapp.go
@@ -3,5 +3,5 @@ package config
 // WopiApp defines the available configuration in order to connect to a WOPI app.
 type WopiApp struct {
 	Addr     string `yaml:"addr" env:"COLLABORATION_WOPIAPP_ADDR" desc:"The URL where the WOPI app is located, such as https://127.0.0.1:8080."`
-	Insecure bool   `yaml:"insecure" env:"COLLABORATION_WOPIAPP_INSECURE" desc:"Connect insecurely"`
+	Insecure bool   `yaml:"insecure" env:"COLLABORATION_WOPIAPP_INSECURE" desc:"Connect to the WOPI app insecurely."`
 }
diff --git a/services/collaboration/pkg/internal/app/wopicontext.go b/services/collaboration/pkg/internal/app/wopicontext.go
index 1bd2a317e..b2f9074d1 100644
--- a/services/collaboration/pkg/internal/app/wopicontext.go
+++ b/services/collaboration/pkg/internal/app/wopicontext.go
@@ -45,7 +45,7 @@ func WopiContextAuthMiddleware(app *DemoApp, next http.Handler) http.Handler {
 				return nil, fmt.Errorf("unexpected signing method: %v", token.Header["alg"])
 			}
 
-			return []byte(app.Config.Secret), nil
+			return []byte(app.Config.JWTSecret), nil
 		})
 
 		if err != nil {
@@ -62,7 +62,7 @@ func WopiContextAuthMiddleware(app *DemoApp, next http.Handler) http.Handler {
 
 		ctx := r.Context()
 
-		wopiContextAccessToken, err := DecryptAES([]byte(app.Config.Secret), claims.WopiContext.AccessToken)
+		wopiContextAccessToken, err := DecryptAES([]byte(app.Config.JWTSecret), claims.WopiContext.AccessToken)
 		if err != nil {
 			fmt.Println("wopicontext", err)
 			http.Error(w, http.StatusText(http.StatusUnauthorized), http.StatusUnauthorized)
diff --git a/services/collaboration/pkg/server/http/server.go b/services/collaboration/pkg/server/http/server.go
index 5b392d06d..d32db5885 100644
--- a/services/collaboration/pkg/server/http/server.go
+++ b/services/collaboration/pkg/server/http/server.go
@@ -48,7 +48,7 @@ func Server(opts ...Option) (http.Service, error) {
 		),
 		middleware.ExtractAccountUUID(
 			account.Logger(options.Logger),
-			account.JWTSecret(options.Config.Secret), // previously, secret came from Config.TokenManager.JWTSecret
+			account.JWTSecret(options.Config.JWTSecret), // previously, secret came from Config.TokenManager.JWTSecret
 		),
 		/*
 			// Need CORS? not in the original server
diff --git a/services/collaboration/pkg/service/grpc/v0/service.go b/services/collaboration/pkg/service/grpc/v0/service.go
index 22289103c..5c1fe9ad2 100644
--- a/services/collaboration/pkg/service/grpc/v0/service.go
+++ b/services/collaboration/pkg/service/grpc/v0/service.go
@@ -148,7 +148,7 @@ func (s *Service) OpenInApp(
 		appURL = editAppURL
 	}
 
-	cryptedReqAccessToken, err := app.EncryptAES([]byte(s.config.Secret), req.AccessToken)
+	cryptedReqAccessToken, err := app.EncryptAES([]byte(s.config.JWTSecret), req.AccessToken)
 	if err != nil {
 		s.logger.Error().
 			Err(err).
@@ -191,7 +191,7 @@ func (s *Service) OpenInApp(
 	}
 
 	token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
-	accessToken, err := token.SignedString([]byte(s.config.Secret))
+	accessToken, err := token.SignedString([]byte(s.config.JWTSecret))
 
 	if err != nil {
 		s.logger.Error().