From abe600e8163e3d91afea4a69a0606f392fae8be8 Mon Sep 17 00:00:00 2001
From: Richard Petersen <richard.petersen@open-xchange.com>
Date: Fri, 27 Jan 2023 21:55:02 +0100
Subject: [PATCH] Add some documentation about code loading and ssh

---
 README.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/README.md b/README.md
index 7df5f4c..b8b4fd5 100644
--- a/README.md
+++ b/README.md
@@ -92,3 +92,15 @@ configured as a "fallback" or "default" service to answer all requests that are
 to be served by one of the other services (e.g like everything under /api). This should simplify
 the Ingress configuration. One example can be found
 [in the ui-middleware repository](https://gitlab.open-xchange.com/frontend/Infrastructure/ui-middleware/-/blob/main/.gitlab-ci/kubernetes-resources.yaml).
+
+## Some notes on code loading
+
+It is mandatory to load the UI over https with a valid certificate and there are multiple reasons for that. These notes give an overview over the features that are required for code loading and will substantiate the need for https.
+
+- First of all, securing your site with https is not hard anymore. We have e.g. Let's Encrypt and several other ways to achieve this. But which case applies to a use-case is not part of these notes.
+- The UI needs a **service worker** to function. The service worker is used for file-caching and version-mismatch detection (the "reload"-banner). **Service workers** are only loaded over https with valid certificate to prevent man-in-the-middle attacks.
+- The UI consists of many small files, because it cannot be bundled as before. To improve file transfer time, HTTP/2 is required which requires https.
+- The **service worker** also increases boot time by loading zipped chunks of files and puts them in the browser-cache on initial boot. Without https no **service worker**, without **service worker** no zipped loading.
+- To reduce the transferred file-size, the **UI-middleware** uses **brotli** encoding for every transferred file (except the index.html). The UI-middleware will not check for accept-enconding headers due to performance reasons. Modern browsers will not load brotli over insecure connections and the UI won't load without it.
+
+It is noteworthy that localhost is an exception to the above rules and the UI including **service workers** and preloading (but not http2) will work on localhost for development environments.
-- 
GitLab