Continue structural port from Spring Boot to Undertow

- Configuration options - Configuration documentation
2018-12-31 15:07:49 +01:00
parent ace5918342
commit 4185b644b7
48 changed files with 454 additions and 351 deletions
--- a/docs/threepids/medium/email/smtp-connector.md
+++ b/docs/threepids/medium/email/smtp-connector.md
@@ -5,15 +5,17 @@ Connector ID: `smtp`

 ## Configuration
 ```yaml
-threepid.medium.email:
-  identity:
-    from: 'identityServerEmail@example.org'
-    name: 'My Identity Server'
-  connectors:
-    smtp:
-      host: 'smtpHostname'
-      port: 587
-      tls: 1 # 0 = no STARTLS, 1 = try, 2 = force
-      login: 'smtpLogin'
-      password: 'smtpPassword'
+threepid:
+  medium:
+    email:
+      identity:
+        from: 'identityServerEmail@example.org'
+        name: 'My Identity Server'
+      connectors:
+        smtp:
+          host: 'smtpHostname'
+          port: 587
+          tls: 1 # 0 = no STARTLS, 1 = try, 2 = force
+          login: 'smtpLogin'
+          password: 'smtpPassword'
 ```
--- a/docs/threepids/medium/msisdn/twilio-connector.md
+++ b/docs/threepids/medium/msisdn/twilio-connector.md
@@ -5,7 +5,12 @@ Connector ID: `twilio`

 ## Configuration
 ```yaml
-threepid.medium.msisdn.connectors.twilio.accountSid: 'myAccountSid'
-threepid.medium.msisdn.connectors.twilio.authToken: 'myAuthToken'
-threepid.medium.msisdn.connectors.twilio.number: '+123456789'
+threepid:
+  medium:
+    msisdn:
+      connectors:
+        twilio:
+          accountSid: 'myAccountSid'
+          authToken: 'myAuthToken'
+          number: '+123456789'
 ```
--- a/docs/threepids/notification/basic-handler.md
+++ b/docs/threepids/notification/basic-handler.md
@@ -18,20 +18,23 @@ This handler can be used with the 3PID types:
 ## Configuration
 Enabled by default or with:
 ```yaml
-notification.handler.email: 'raw'
+notification:
+  handler:
+    email: 'raw'
 ```

 **WARNING:** Will be consolidated soon, prone to breaking changes.  
 Structure and default values:
 ```yaml
-threepid.medium:
-  email:
-    identity:
-      from: ''
-      name: ''
-    connector: 'smtp'
-    generator: 'template'
-  msisdn:
-    connector: 'twilio'
-    generator: 'template'
+threepid:
+  medium:
+    email:
+      identity:
+        from: ''
+        name: ''
+      connector: 'smtp'
+      generator: 'template'
+    msisdn:
+      connector: 'twilio'
+      generator: 'template'
 ```
--- a/docs/threepids/notification/sendgrid-handler.md
+++ b/docs/threepids/notification/sendgrid-handler.md
@@ -1,7 +1,39 @@
 # SendGrid Notification handler
-To be completed. See [raw possible configuration items](https://github.com/kamax-matrix/mxisd/blob/master/src/main/resources/application.yaml#L172).
+> **WARNING:** This section is incomplete and may be misleading. Contact us if guidance is needed.

-Enabled with:
+Enable with:
 ```yaml
-notification.handler.email: 'sendgrid'
+notification:
+  handler:
+    email: 'sendgrid'
 ```
+
+Available Configuration keys:
+```yaml
+notification:
+  handlers:
+    sendgrid:
+      api:
+        key: <API key>
+      identity:
+        from: <Sender email address>
+        name: <Sender name>
+      templates:
+        invite:
+          subject: <Subject of the email notification sent for room invites>
+          body:
+            text: <Path to file containing the raw text part of the email. Do not set to not use one>
+            html: <Path to file containing the HTML part of the email. Do not set to not use one>
+        session:
+          validation:
+            local:
+              subject: <Subject of the email notification sent for local 3PID sessions>
+              body:
+                text: <Path to file containing the raw text part of the email. Do not set to not use one>
+                html: <Path to file containing the HTML part of the email. Do not set to not use one>
+            remote:
+              subject: <Subject of the email notification sent for remote 3PID sessions>
+              body:
+                text: <Path to file containing the raw text part of the email. Do not set to not use one>
+                html: <Path to file containing the HTML part of the email. Do not set to not use one>
+``` 
--- a/docs/threepids/notification/template-generator.md
+++ b/docs/threepids/notification/template-generator.md
@@ -11,16 +11,18 @@ placeholders and also have their own individual set of placeholders.
 ## Configuration
 To configure paths to the various templates:
 ```yaml
-threepid.medium.<YOUR 3PID MEDIUM HERE>:
-  generators:
-    template:
-      invite: '/path/to/invite-template.eml'
-      session:
-        validation:
-          local: '/path/to/validate-local-template.eml'
-          remote: 'path/to/validate-remote-template.eml'
-      generic:
-        matrixId: '/path/to/mxid-invite-template.eml'
+threepid:
+  medium:
+    <YOUR 3PID MEDIUM HERE>:
+      generators:
+        template:
+          invite: '/path/to/invite-template.eml'
+          session:
+            validation:
+              local: '/path/to/validate-local-template.eml'
+              remote: 'path/to/validate-remote-template.eml'
+          generic:
+            matrixId: '/path/to/mxid-invite-template.eml'
 ```
 The `template` generator is usually the default, so no further configuration is needed.

--- a/docs/threepids/session/session-views.md
+++ b/docs/threepids/session/session-views.md
@@ -6,21 +6,23 @@ Pseudo-configuration to illustrate the structure:
 ```yaml
 # CONFIGURATION EXAMPLE
 # DO NOT COPY/PASTE THIS IN YOUR CONFIGURATION
-view.session.local:
-  onTokenSubmit:
-    success: '/path/to/session/local/tokenSubmitSuccess-page.html'
-    failure: '/path/to/session/local/tokenSubmitFailure-page.html'
-view.session.localRemote:
-  onTokenSubmit:
-    success: '/path/to/session/localRemote/tokenSubmitSuccess-page.html'
-    failure: '/path/to/session/local/tokenSubmitFailure-page.html'
-view.session.remote:
-  onRequest:
-    success: '/path/to/session/remote/requestSuccess-page.html'
-    failure: '/path/to/session/remote/requestFailure-page.html'
-  onCheck:
-    success: '/path/to/session/remote/checkSuccess-page.html'
-    failure: '/path/to/session/remote/checkFailure-page.html'
+view:
+  session:
+    local:
+      onTokenSubmit:
+        success: '/path/to/session/local/tokenSubmitSuccess-page.html'
+        failure: '/path/to/session/local/tokenSubmitFailure-page.html'
+    localRemote:
+      onTokenSubmit:
+        success: '/path/to/session/localRemote/tokenSubmitSuccess-page.html'
+        failure: '/path/to/session/local/tokenSubmitFailure-page.html'
+    remote:
+      onRequest:
+        success: '/path/to/session/remote/requestSuccess-page.html'
+        failure: '/path/to/session/remote/requestFailure-page.html'
+      onCheck:
+        success: '/path/to/session/remote/checkSuccess-page.html'
+        failure: '/path/to/session/remote/checkFailure-page.html'
 # CONFIGURATION EXAMPLE
 # DO NOT COPY/PASTE THIS IN YOUR CONFIGURATION
 ```
--- a/docs/threepids/session/session.md
+++ b/docs/threepids/session/session.md
@@ -133,19 +133,22 @@ file unless you want to specifically overwrite them.
 ```yaml
 # CONFIGURATION EXAMPLE
 # DO NOT COPY/PASTE THIS IN YOUR CONFIGURATION
-session.policy.validation.enabled: true
-session.policy.validation.forLocal:
-  enabled: true
-  toLocal: true
-  toRemote:
-    enabled: true
-    server: 'configExample'  # Not to be included in config! Already present in default config!
-session.policy.validation.forRemote:
-  enabled: true
-  toLocal: true
-  toRemote:
-    enabled: true
-    server: 'configExample'  # Not to be included in config! Already present in default config!
+session:
+  policy:
+    validation:
+      enabled: true
+      forLocal:
+        enabled: true
+        toLocal: true
+        toRemote:
+          enabled: true
+          server: 'configExample'  # Not to be included in config! Already present in default config!
+      forRemote:
+        enabled: true
+        toLocal: true
+        toRemote:
+          enabled: true
+          server: 'configExample'  # Not to be included in config! Already present in default config!
 # DO NOT COPY/PASTE THIS IN YOUR CONFIGURATION
 # CONFIGURATION EXAMPLE
 ```
@@ -219,17 +222,20 @@ On the flip side, people with *Remote* 3PID scopes will not be found from other

 Use the following values:
 ```yaml
-session.policy.validation.enabled: true
-session.policy.validation.forLocal:
-  enabled: true
-  toLocal: true
-  toRemote:
-    enabled: false
-session.policy.validation.forRemote:
-  enabled: true
-  toLocal: true
-  toRemote:
-    enabled: false
+session:
+  policy:
+    validation:
+      enabled: true
+      forLocal:
+        enabled: true
+        toLocal: true
+        toRemote:
+          enabled: false
+      forRemote:
+        enabled: true
+        toLocal: true
+        toRemote:
+          enabled: false
 ```

 **IMPORTANT**: When using local-only mode and if you are using synapse, you will also need to enable its dedicated Identity
@@ -245,17 +251,20 @@ Typical use cases:

 Use the following values:
 ```yaml
-session.policy.validation.enabled: true
-session.policy.validation.forLocal:
-  enabled: true
-  toLocal: false
-  toRemote:
-    enabled: true
-session.policy.validation.forRemote:
-  enabled: true
-  toLocal: false
-  toRemote:
-    enabled: true
+session:
+  policy:
+    validation:
+      enabled: true
+      forLocal:
+        enabled: true
+        toLocal: false
+        toRemote:
+          enabled: true
+      forRemote:
+        enabled: true
+        toLocal: false
+        toRemote:
+          enabled: true
 ```

 #### Sessions disabled
@@ -272,5 +281,8 @@ It is therefore recommended to not fully disable sessions but instead restrict s

 Use the following values to enable this mode:
 ```yaml
-session.policy.validation.enabled: false
+session:
+  policy:
+    validation:
+      enabled: false
 ```