commit b483212b7033c49f16553eadaed1971be8d08c37
parent 7ec2005964683f4ea5340b51f096eb99f37af709
Author: Michał M. Sapka <michal@sapka.me>
Date: Fri, 14 Jul 2023 11:52:12 +0200
doc: write README
Diffstat:
| M | README | | | 86 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----- |
1 file changed, 81 insertions(+), 5 deletions(-)
diff --git a/README b/README
@@ -1,8 +1,84 @@
-PLAPROXY
+PLAPROX - A proxy for plausible.io scripts
+==========================================
+Plaprox is a *NIX proxy demeon for Plausible scripts.
-=========================
-A proxy for plausible.io scripts
+Raison d'etre
+-------------
+I run my personal homepage under https://michal.sapka.me. I have chosen Plausible
+(https://plausible.io) as my provider of visitor stats as it gives me all I want
+while not trying to track visitors - as some other competitors do.
-!!!!!!!!!!!!!!!
-does not work yet
+However, many cybernauts use adblockers. I certainly do. Sometimes those blockers
+are overprotective and block all stats providers - like Plausible. I consider
+Plausible as a very much Ok service. To see who actually visits my sites, I need
+to proxy all requests to Plausible via a local proxy.
+
+You can read more at https://plausible.io/docs/proxy/introduction.
+
+I have done it for quite some time, but recently I've moved from Linux/Nginx to
+OpenBSD/Httpd/Relayd. I love this setup, but it does not provide proxy_pass.
+
+So I wrote this little fella.
+
+
+Architecture
+------------
+Not much here. It's a *NIX daemon that listens on port 9090 and will proxy
+predefined paths to Plausible and return the returned data back to the user.
+
+
+Go
+--
+I am not a Go developer. Far from it, as I come from Ruby background. This means
+that this is not a proper Go code. I've been learning the language a bit before
+starting to write Plaprox, and this is my first (and, as of writing this - the
+only) project written in Go. Just for teh lulz.
+
+
+Contributing
+------------
+Found this interesting? Cool! Know how to improve things? Even better! Email me
+a git patch - my email can be found at https://michal.sapka.me/about/.
+
+
+Known problems
+--------------
+- GET requests can be cached. Plaprox does not currently do this.
+
+
+Testing
+-------
+You can run the tests via:
+
+ go test
+
+
+Compiling
+---------
+You need Go to compile Plaproxy. After that, compiling is simple:
+
+ go build
+
+Note that, as for, now I do not provide binary files. You need do perform the
+compilation on the same OS and architecture as the target system. So, if you run
+Plaprox on OpenBSD ARM64, compile it on OpenBSD ARM64.
+
+
+Running
+-------
+You can run the app as a process:
+
+ ./plaprox
+
+But the preferred way is to treat it a demon. Please refer to documentation of
+your OS of choice
+
+
+Configuration
+-------------
+To proxy other endpoints, you need to modify the source code. Look at method
+serveProxy() in main.go. Add another handleFunc for the required path, and any
+requests to the proxy will be handled automatically:
+
+ http.HandleFunc("/another/proxied/path.js", Proxy)
