From 496b1686775cfb84fa9bad8717561aec12a32590 Mon Sep 17 00:00:00 2001
From: Lili <pastrnakie@seznam.cz>
Date: Mon, 12 Sep 2022 09:36:36 +0200
Subject: [PATCH] include basic readme

---
 README.md | 88 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 88 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a4a9734
--- /dev/null
+++ b/README.md
@@ -0,0 +1,88 @@
+# Tlapbot
+Tlapbot is an [Owncast](https://owncast.online/) bot, aiming to add the feature of channel points and
+channel point redeems to Owncast.
+
+This bot is currently in-development. The goal is to have a feature set on par
+with Twitch channel points, while making use of Owncast webhooks and especially
+[External actions](https://owncast.online/thirdparty/actions/).
+## Features
+Currently, the bot gives points to everyone in chat -- the interval can be
+configured in the config, as well as the amount of points given.
+
+The users in chat can then use their points on redeems. The bot currently
+only has one hardcoded redeem, but I'd like to make this configurable,
+so that every Owncast streamer can set up their own redeems that best fit
+their stream.
+
+The redeems then show on a "Redeems dashboard" that everyone can view
+at the flask server's URL, which can be included in Owncast
+as an External action, a single button that displays information about
+recent redeems.
+## Setup
+The Python prerequisites for running tlapbot are the libraries `flask`,
+`requests` and `apscheduler`.
+### First time setup
+Install prerequisites:
+```bash
+pip install flask
+pip install requests
+pip install apscheduler
+```
+(Or install them in your virtual environment if you prefer to use one)
+
+Initialize db:
+```bash
+python -m flask init-db
+```
+Create a `tlapbot/config.py` file and fill it in as needed.
+Default values are included in `tlapbot/default_config`, and values in
+`config.py` overwrite them.
+
+Some recommendations:
+```bash
+SECRET_KEY # get one from running `python -c 'import secrets; print(secrets.token_hex())'`
+OWNCAST_ACCESS_TOKEN # get one from owncast instance
+OWNCAST_INSTANCE_URL
+```
+### Owncast setup
+In Owncast, navigate to the admin interface at `/admin`,
+and then go to Integrations.
+#### Access Token
+In Access Tokens, generate an Access Token to put in
+`tlapbot/config.py`. At the moment, the only permission the Access Token needs
+is sending messages, the bot doesn't perform any administrative actions.
+#### Webhook
+In webhooks, you create a Webhook, and point it at your bot's URL with
+`/owncastWebhook` added.
+
+In debug, this will be something like `localhost:5000/owncastWebhook`,
+or, if you're not running the debug Owncast instance and bot on the same machine,
+you can use a tool like [ngrok](https://ngrok.com/)
+to redirect the Owncast traffic to your `localhost`.
+#### External Action
+In External Actions, you point the external action to your bot's URL with `/dashboard` added.
+
+In debug, this might be something like `localhost:5000/dashboard`,
+or you can use a tool like ngrok again.
+
+Example:
+
+URL: MyTlapbotServer.com/dashboard
+
+Action Title: Redeems Dashboard
+
+### Running in debug:
+Set the FLASK_APP variable:
+```bash
+export FLASK_APP=tlapbot
+```
+or in Powershell on Windows:
+```powershell
+$Env:FLASK_APP = "tlapbot"
+```
+Run the app (in debug mode):
+```bash
+python -m flask --debug run 
+```
+### Running in prod:
+To be added when I actually run a prod version of the bot.
\ No newline at end of file