doc: document custom path image

Author: guggero

doc/custom-path.md

@@ -0,0 +1,44 @@
+# Using a custom path for LiT
+
+If required LiT can be built to be accessed through a custom path (e.g. `/lit/`)
+in the browser instead of the default root path (`/`).
+
+To build LiT with a custom path, run the following command:
+
+```shell
+⛰  make PUBLIC_URL=/my-custom-path
+```
+
+**Make sure to not include a `/` at the end of the path.** To revert to the
+original, root path, set the variable to empty (`make PUBLIC_URL=`) or leave
+it out completely.
+
+## Docker image built with a path prefix
+
+There is a docker image that's automatically built with the prefix `/lit`
+available on Docker Hub. Just append `-path-prefix` to any version tag (after
+`v0.5.2-alpha`). For example:
+
+```shell
+# Default image.
+⛰  docker pull lightninglabs/lightning-terminal:v0.5.3-alpha
+
+# Image with /lit path prefix.
+⛰  docker pull lightninglabs/lightning-terminal:v0.5.3-alpha-path-prefix
+```
+
+## Use with nginx reverse proxy
+
+There is [an example nginx](example-nginx.conf) config file that demonstrates
+how rewrite rules can be set up to run LiT under the `/lit` path prefix (and
+internally forward all `grpc-web` requests to the LiT proxy while still
+forwarding "native" gRPC requests to the `lnd` instance that's also running
+behind the nginx reverse proxy).
+
+The example reverse proxy can be run with:
+
+```shell
+⛰  cd docs
+⛰  docker run --name lit-nginx \
+      -v $(pwd)/example-nginx.conf:/etc/nginx/nginx.conf:ro -p 8081:80 -d nginx
+```

doc/example-nginx.conf

@@ -0,0 +1,57 @@
+events {
+  worker_connections  1024;
+}
+
+http {
+    # Redirect all incoming grpc-web requests to the LiT proxy. Everything else
+    # goes directly to the internal lnd container. We use a temporary variable
+    # here so we can rewrite it to the actual host again in the next map
+    # directive.
+    map $content_type $tmp_backend {
+      "application/grpc-web+proto" "172.17.0.1:8443"; # LiT proxy.
+      default "localhost:10009"; # main LND
+    }
+
+    # Streaming grpc-web requests can be identified by the
+    # "Sec-WebSocket-Protocol: grpc-websockets" header field. So those requests
+    # also need to go to the LiT proxy.
+    map $http_sec_websocket_protocol $lnd_backend {
+      "grpc-websockets" "172.17.0.1:8443"; # LiT proxy.
+      default $tmp_backend; # Fall back to the value from the above map result.
+    }
+
+    # Make sure WebSockets are properly upgraded.
+    map $http_sec_websocket_protocol $lnd_connection {
+      "grpc-websockets" "upgrade";
+      default $http_connection;
+    }
+
+    server {
+        listen 80;
+        server_name localhost;
+
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Origin  https://$lnd_backend;
+        proxy_set_header Connection $lnd_connection;
+
+        location /lit {
+            # This needs a slash at the end!
+            proxy_pass https://172.17.0.1:8443/;
+        }
+
+        location ~* ^/lnrpc.Lightning/ {
+            # This cannot have a slash at the end!
+            proxy_pass https://$lnd_backend;
+        }
+
+        location ~* ^/looprpc.SwapClient/ {
+            # This cannot have a slash at the end!
+            proxy_pass https://$lnd_backend;
+        }
+
+        location ~* ^/poolrpc.Trader/ {
+            # This cannot have a slash at the end!
+            proxy_pass https://$lnd_backend;
+        }
+    }
+}