From ef3e18931a08134f2858aec0d90b41bae6ca9ec0 Mon Sep 17 00:00:00 2001 From: Jaidyn Ann <10477760+JadedCtrl@users.noreply.github.com> Date: Tue, 8 Aug 2023 16:11:01 -0500 Subject: [PATCH] README.md and helper script --- README.md | 104 +++++++++++++++++++++++++++++++++++++++++++ run-kaptchapelo.lisp | 10 +++++ 2 files changed, 114 insertions(+) create mode 100644 README.md create mode 100755 run-kaptchapelo.lisp diff --git a/README.md b/README.md new file mode 100644 index 0000000..33c0dec --- /dev/null +++ b/README.md @@ -0,0 +1,104 @@ +# Kaptĉapelo +Kaptĉapelo is a simple [Kocaptcha](https://github.com/koto-bank/kocaptcha)-compatible CAPTCHA server, to keep out robots and people with dubious intent. Rather than auto-generated challenges like Kocaptcha, though, Kaptĉapelo lets you create shiny, pretty, _custom_ challenges. + +Since Kaptĉapelo is a kinda-sorta drop-in replacement for Kocaptcha, you can [use it as CAPTCHA](https://docs-develop.pleroma.social/backend/configuration/cheatsheet/#captcha) for your [Pleroma](https://pleroma.social) server. + + + +## Installation +### Setup +Kaptĉapelo requires the following: + +* A Common Lisp implementation. I’d recommend [Steel Bank Common Lisp](http://www.sbcl.org/), which is robust and available on many operating systems under the package-name `sbcl`. +* [Quicklisp](https://quicklisp.org/), a “package-manager” for Common Lisp libraries. + +To install these, you can run the following commands (replacing `guix` with your package-manager of choice)… + +``` +$ guix install sbcl +$ mkdir --parents ~/.local/lib/quicklisp/ +$ wget https://beta.quicklisp.org/quicklisp.lisp +$ sbcl --load quicklisp.lisp +``` + +And then, in SBCL, run… + +``` +* (quicklisp-quickstart:install :path "~/.local/lib/quicklisp/") +* (ql:add-to-init-file) +* (quit) +``` + +Back in the shell, we can clone Kaptĉapelo… + +``` +$ cd ~/.local/lib/quicklisp/local-projects/ +$ git clone https://notabug.org/jadedctrl/kaptchapelo +``` + + +### Execution +In the sources, you can find a script (`run-kaptchapelo.lisp`), which can be used like so: + +``` +$ # First, let’s make it executable… +$ chmod +x ~/.local/lib/quicklisp/local-projects/kaptchapelo/run-kaptchapelo.lisp +$ # … now we can run it… +$ ~/.local/lib/quicklisp/local-projects/kaptchapelo/run-kaptchapelo.lisp +``` + +Now, Kaptchapelo should be running and good to go; visit http://localhost:5001 and have a look! + + + +## Configuration +### Web-server +You’ll probably be running Kaptchapelo through a reverse proxy; here’s how you can add it to an existing server definition with [nginx](https://nginx.org/): + +``` +server { + […] + + location /new { + set $target http://localhost:5001; + proxy_buffering off; + proxy_pass http://localhost:5001; + } + + location /captcha/ { + set $target http://localhost:5001; + proxy_buffering off; + proxy_pass http://localhost:5001; + } + + […] +} +``` + +That is to say, you don’t need a dedicated subdomain! + + +### Custom captchas +Making custom captchas is easy! A challenge is simply a PNG file (question) and a TXT file (answer). +… that’s it! Literally. + +Note that the PNG and TXT files should have the same name (bird.png and bird.txt, not bird2.png and bird1.txt), and that the TXT answer should consist of one line with _no_ newline. + +A peek through this repository’s example captchas (in `./captcha/`) should give you the idea. + + +### Captcha directory +It’s likely you’ll want to provide a custom directory in which to store your captchas; no problem! Just edit the aforementioned `run-kaptchapelo.lisp` script, which contains a line… + +``` +:captcha-directory #p"~/.local/lib/quicklisp/local-projects/kaptchapelo/captcha/" +``` + +… all you have to do is replace the path there with your own. +In addition, you can also change the port and address by editing this script. + + + +## Misc. information +Author: Jaidyn Ann @jadedctrl@jam.xwx.moe +License: GNU AGPLv3 diff --git a/run-kaptchapelo.lisp b/run-kaptchapelo.lisp new file mode 100755 index 0000000..cea6301 --- /dev/null +++ b/run-kaptchapelo.lisp @@ -0,0 +1,10 @@ +#!/usr/bin/env -S sbcl --script + +(load #p"~/.local/lib/quicklisp/setup.lisp") +(ql:quickload :kaptchapelo) + +(kaptchapelo:start-server + ;; Change captcha-directory’s path to your captchas + :captcha-directory #p"~/.local/lib/quicklisp/local-projects/kaptchapelo/captcha/" + :address "0.0.0.0" + :port 5001)