From 439a87dec9ab55cf0046f4652c59f332e8a136dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ferdinand=20M=C3=BCtsch?= Date: Fri, 11 Dec 2020 22:58:07 +0100 Subject: [PATCH] docs: advanced setup instructions for client-side reverse proxy --- README.md | 7 +++++-- docs/advanced_setup.md | 29 +++++++++++++++++++++++++++++ 2 files changed, 34 insertions(+), 2 deletions(-) create mode 100644 docs/advanced_setup.md diff --git a/README.md b/README.md index 07944a3..1d1c3d1 100644 --- a/README.md +++ b/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 diff --git a/docs/advanced_setup.md b/docs/advanced_setup.md new file mode 100644 index 0000000..1b7eab1 --- /dev/null +++ b/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 \ No newline at end of file