wakapi/docs/advanced_setup.md

Advanced Setup

This page contains instructions for additional setup options, none of which are mandatory.

Optional: Client-side proxy

Most Wakatime plugins work in a way that, for every heartbeat to send, the plugin calls your local wakatime-cli (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.

Option 1: tinyproxy forward proxy (Linux, Mac only)

In this example we use tinyproxy as a small, easy-to-install proxy server, written in C, that runs on your local machine.

1. Install tinyproxy
   • Fedora / RHEL: dnf install tinyproxy
   • Debian / Ubuntu: apt install tinyproxy
   • MacOS: Install from MacPorts
2. Enable and start it
   • Linux: sudo systemctl start tinyproxy && sudo systemctl enable tinyproxy
   • Mac: Not sure, sorry ¯_(ツ)_/¯
3. Update ~/.wakatime.cfg
   • Set proxy = http://localhost:8888
4. Done
   • All Wakapi requests are passed through tinyproxy now, which keeps a TCP connection with the server open for some time

Option 2: Caddy reverse proxy (Win, Linux, Mac)

In this example, we misuse Caddy, which is a web server and reverse proxy, to fulfil the above scenario.

1. Install Caddy
   • When installing manually, don't forget to set up a systemd service to start Caddy on system startup
2. 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
       }
   }
   

3. Restart Caddy
4. Verify that you can access http://localhost:8070/api/health
5. Update ~/.wakatime.cfg
   • Set api_url = http://localhost:8070/api/heartbeat
6. Done
   • All Wakapi requests are passed through Caddy now, which keeps a TCP connection with the server open for some time