Merge pull request #21 from nordeck/nic/feat/docs

Improve docs

backend/README.md

@@ -8,7 +8,12 @@ An authorization mechanism is implemented in conjunction with the frontend, whic
 submitted by authorized [Matrix](https://matrix.org) users
 through [Matrix UVS](https://github.com/matrix-org/matrix-user-verification-service/).
 
-## How To Use
+## Installation
+
+This application needs its REST port (default `8080`) exposed to the network where it is reachable from your clients, which typically means it's open to the internet.
+Because sensitive information such as secret tokens are exchanged between clients and the backend, HTTPS (TLS) should be used to avoid leaking those secrets.
+Terminating TLS is out of scope for this app; we suggest using a reverse proxy or ingress of your choice that fits your deployment environment.
+The appropriate publicly reachable address must be [configured in Jitsi](https://github.com/nordeck/feedback-application/blob/main/jitsi-feedback-plugin/README.md#required-jitsi-configuration) using the setting `config.feedbackBackend`.
 
 To clone and run this application, you'll need [Git](https://git-scm.com) as well as [Docker](https://docker.com/)
 installed and configured on your computer.
@@ -19,7 +24,7 @@ installed and configured on your computer.
     1. `cd backend`
     2. `docker build --tag=nordeck/feedback-app .`
     3. `docker run nordeck/feedback-app` with the fitting environment and port publishing parameters for your setup
-4. Run Grafana with the [provided dashboard](../grafana) (optional)
+4. (optional) Run Grafana with the [provided dashboard](../grafana)
 
 ## Configuration
 

jitsi-feedback-plugin/README.md

@@ -1,15 +1,20 @@
-### How to install the custom analytics feedback handler
+# Jitsi Feedback Plugin
 
+## Installation
 
-Mount the `feedback.js` to the root of the jitsi-meet application.
-For example, the location inside the jitsi-meet web container is `/usr/share/jitsi-meet/feedback.js`.
+We suggest to mount the `feedback.js` to the root of the jitsi-meet application, matching the path set in `config.analytics.scriptURLs`.
+For example, the location inside the jitsi-meet web container is `/usr/share/jitsi-meet/feedback.js`, and it will be reachable from clients at `/feedback.js`.
+
+If required by your special use case, it is technically possible to host `feedback.js` anywhere you want as long as clients can reach it. Simply adjust the path given in the `scriptURLs` config setting needs to match.
+
+### Required Jitsi configuration
 
 These are the relevant settings that need to be set in jitsi-meet.
 The intended way to configure this is by leveraging the `custom-config.js` method.
 
 ```javascript
 // address of the feedback backend REST API, reachable from the end user device
-config.feedbackBackend = 'http://localhost:8080'
+config.feedbackBackend = 'https://example.org:8080'
 
 // percentage of users to automatically request feedback from when leaving the call
 // it's 100 by default if undefined, i.e. always shown