From 4bc3745009760c80008a433a5aa4eb3dfb1f0494 Mon Sep 17 00:00:00 2001
From: fungal <fungal@locahlo.st>
Date: Sat, 23 Dec 2023 15:56:15 +0100
Subject: [PATCH] Add readme / documentation

---
 README.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)

diff --git a/README.md b/README.md
index e69de29..c3ae893 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,72 @@
+# Emojiquest
+
+Are your users often asking you to add a new emoji on your instance, and you keep forgetting to add them?
+Then Emojiquest might be the answer for you!
+
+It's a simple web service on which users can submit an emoji request with the shortcode the emoji should have (helping you to name emoji) and the URL for the image that should be used as emoji.
+No registration required!
+
+## Installation
+
+I will likely not provide binary because I can't be bothered to support all architecture, sorry.
+However, it's made purely in Go, it's a breeze to install and compile.
+You can get Go from the [Go download page](https://go.dev/dl/).
+Clone this repository and run `go build` to generate the binary.
+
+The following systemd unit (`/lib/systemd/system/emojiquest.service`) is enough to have it run as a service:
+``` ini
+[Unit]
+Description=emojiquest
+
+[Service]
+Type=simple
+Restart=always
+RestartSec=5s
+# change path to your relevant binary location
+ExecStart=/opt/emojiquest -listen [::1]:8090 -requests /srv/emojiquest/requests.txt
+WorkingDirectory=/srv/emojiquest/
+ReadWritePaths=/srv/emojiquest/
+DynamicUser=yes
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Create the file that will hold all the request, and its parent directory:
+``` shell
+mkdir /srv/emojiquest/
+chown root:root /srv/emojiquest/
+touch /srv/emojiquest/requests.txt
+chmod 777 /srv/emojiquest/requests.txt
+```
+And start the service with `systemctl enable --now emojiquest.service`
+
+Configuring reverse proxy or leaving the service open on the internet is left at the reader discretion.
+
+## Security And Safety Concerns
+
+The software is given without any warranty, run it at your own risk and liability.
+
+No special measures are made to protect the service and its runtime.
+Tho its side effects are very little and easy to audit ([read the file `main.go`](./main.go)).
+Actions are appened-only, no deletion is ever done.
+With systemd sandboxing the service has barely no surface to mess with the system but its own data.
+
+If you wish to prevent the whole internet to request you emoji or doing DoS with the service, you can use [OAuth2-Proxy](https://github.com/oauth2-proxy/oauth2-proxy).
+Here is a start-up snippet for it, using Keycloak provider:
+
+``` shell
+~/go/bin/oauth2-proxy --provider keycloak-oidc \
+             --provider-display-name 'login with SSO' \
+             --client-id 'emojiquest' \
+             --client-secret '<insert here the client secret>' \
+             --redirect-url 'https://emojiquest.example.com/oauth2/callback' \
+             --cookie-secure=true \
+             --cookie-secret='<insert here the cookie secret>' \
+             --email-domain=* \
+             --oidc-issuer-url=https://accounts.example.com/realms/<your realm> \
+             --code-challenge-method=S256 \
+             --upstream http://localhost:8090
+```
+
+If you wish to use your instance as an OAuth2 provider it's currently no possible due to how it's made, see the [feature request issue](https://github.com/oauth2-proxy/oauth2-proxy/issues/2226).