docs: advanced setup instructions for client-side reverse proxy

README.md

@@ -75,8 +75,7 @@ You can specify configuration options either via a config file (default: `config
 | `server.base_path`          | `WAKAPI_BASE_PATH`          | `/`            | Web base path (change when running behind a proxy under a sub-path) |
 | `security.password_salt`    | `WAKAPI_PASSWORD_SALT`      | -              | Pepper to use for password hashing                                  |
 | `security.insecure_cookies` | `WAKAPI_INSECURE_COOKIES`   | `false`        | Whether or not to allow cookies over HTTP                           |
-| `security.cookie_max_age`   | `WAKAPI_COOKIE_MAX_AGE  `   | `172800`       | Lifetime of authentication cookies in seconds or `0` to use [Session](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#Define_the_lifetime_of_a_cookie) cookies 
+| `security.cookie_max_age`   | `WAKAPI_COOKIE_MAX_AGE  `   | `172800`       | Lifetime of authentication cookies in seconds or `0` to use [Session](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#Define_the_lifetime_of_a_cookie) cookies |
-|
 | `db.host`                   | `WAKAPI_DB_HOST`            | -              | Database host                                                       |
 | `db.port`                   | `WAKAPI_DB_PORT`            | -              | Database port                                                       |
 | `db.user`                   | `WAKAPI_DB_USER`            | -              | Database user                                                       |
@@ -98,6 +97,10 @@ api_key = the_api_key_printed_to_the_console_after_starting_the_server`
 
 You can view your API Key after logging in to the web interface.
 
+### Optional: Client-side proxy
+
+See the [advanced setup instructions](docs/advanced_setup.md).  
+
 ## 🔵 Customization
 
 ### Aliases

docs/advanced_setup.md

@@ -0,0 +1,29 @@
+# Advanced Setup
+## Optional: Client-side proxy
+Most Wakatime plugins work in a way that, for every heartbeat to send, the plugin calls your local [wakatime-cli](https://github.com/wakatime/wakatime) (a small Python program that is automatically installed when installing a Wakatime plugin) with a few command-line arguments, which is then run as a new process. Inside that process, a heartbeat request is forged and sent to the backend API – Wakapi in this case.
+
+While this is convenient for plugin developers, as they do not have to deal with sending HTTP requests, etc., it comes with a minor drawback. Because the CLI process shuts down after each request, its TCP connection is closed as well. Accordingly, **TCP connections cannot be re-used** and every single heartbeat request is inevitably preceded by the `SYN` + `SYN ACK` + `ACK` sequence for establishing a new TCP connection as well as a handshake for establishing a new TLS session.
+
+While this certainly does not hurt, it is still a bit of overhead. You can avoid that by setting up a local reverse proxy on your machine, that keeps running as a daemon and can therefore keep a continuous connection.
+
+In this example, [Caddy](https://caddyserver.com) is used as an easy-to-set-up webserver / reverse proxy.
+
+1. [Install Caddy](https://caddyserver.com/)
+    * When installing manually, don't forget to set up a systemd service to start Caddy on system startup
+1. Create a Caddyfile
+    ```
+    # /etc/caddy/Caddyfile
+   
+    http://localhost:8070 {
+        reverse_proxy * {
+            to https://wakapi.dev  # <-- substitute your own Wakapi host here
+            header_up Host {http.reverse_proxy.upstream.host}
+            header_down -Server
+        }
+    }
+    ```
+1. Restart Caddy
+1. Verify that you can access [`http://localhost:8070/api/health`](http://localhost:8070/api/health)
+1. Update `~/.wakatime.cfg`
+    * Set `api_url = http://localhost:8070/api/heartbeat`
+1. Done