lili
/
Tlapbot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 6 Wiki Activity

README.md update: wording, prod install+running 

also prepared headings for the config.py and redeems.py explainer
This commit is contained in:
Lili (Tlapka) 2022-11-14 14:46:44 +01:00
parent 0182d323d2
commit 07959e03ce
1 changed files with 81 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

101
README.md
View File

@ -2,34 +2,37 @@
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
This bot is currently in-development. The goal is to have an experience similar
to [Twitch channel points](https://help.twitch.tv/s/article/viewer-channel-point-guide), while making use of [Owncast webhooks](https://owncast.online/thirdparty/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 bot gives points to everyone in chat -- 10 points every 10 minutes by
default, but the time interval and amount of points can be changed in the config.
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 users in chat can then use their points on redeems -- rewards like "choose my
background music", "choose what level to play next", "react to this video" etc.
The streamer can configure redeems to fit their stream and the activity they're
doing, to add more viewer-streamer interactions to the 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.
as an External Action on the Owncast stream, or at its standalone URL.
This allows easy browsing of active challenges and recent redeems, for
both the streamer and the viewers.
## Setup
The Python prerequisites for running tlapbot are the libraries `flask`,
`requests` and `apscheduler`.
### Dev setup (from git repository)
`requests` and `apscheduler`. If you follow the installation steps below,
they should automatically be installed if you don't have them.
**The only difference between installing the project as a folder and installing from a package file is that the `instance` folder will be in a slightly different place. (And that you can more easily change the code when running the project from a folder.)**
### Install from git repo (as a folder)
1. Clone the repository.
2. Run `pip install -e .` in the root folder. This will install tlapbot
as a package in editable more, along with all its prerequisites.
3. Initialize db:
as a package in editable more.
3. Initialize the database:
```bash
python -m flask init-db
```
4. Create an `instance/config.py` file and fill it in as needed.
4. Create a `instance/config.py` file and fill it in as needed.
Default values are included in `tlapbot/default_config`, and values in
`config.py` overwrite them. (The database also lives in the `instance` folder
by default.)
@ -40,6 +43,36 @@ by default.)
OWNCAST_ACCESS_TOKEN # get one from owncast instance
OWNCAST_INSTANCE_URL # default points to localhost owncast on default port
```
5. OPTIONAL: Create an `instance/redeems.py` file and add your custom redeems.
If you don't add a redeems file, the bot will initialize the default redeems from `tlapbot/default_redeems.py`.
More details on how to write the config and redeems files are written later in the readme.
### Install from a .whl package file
On my live owncast instance, I like to run the bot from a `.whl` package file.
I'll include those in releases, but you can also compile your own
by cloning the repository, installing the `wheel` package and then running `python setup.py bdist_wheel`. The `.whl` file will be saved in the `dist` folder.
1. Download the `.whl` file or create your own. Move it to your server and set up your Python virtual environment.
(I'm not sure what happens when you do all this without a virtual environment, so please do actually set one up if you're doing this.)
2. Run `pip install tlapbot-[version].whl`. This will install the package.
3. Initialize the database:
```bash
python -m flask init-db
```
4. Create a `/[venv]/var/tlapbot-instance/config.py` file and fill it in as needed. (`[venv]` is what you called your virtual environment.)
Default values are included in `tlapbot/default_config`, and values in
`config.py` overwrite them. (The database also lives in the `tlapbot-instance` folder
by default.)
Tlapbot might not work if you don't overwrite these:
```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 # default points to localhost owncast on default port
```
5. OPTIONAL: Create an `/[venv]/var/tlapbot-instance/config.py` file and add your custom redeems.
If you don't add a redeems file, the bot will initialize the default redeems from `tlapbot/default_redeems.py`.
More details on how to write the config and redeems files are written later in the readme.
## Owncast setup
In Owncast, navigate to the admin interface at `/admin`,
and then go to Integrations.
@ -84,13 +117,41 @@ Run the app (in debug mode):
python -m flask --debug run
```
### Running in prod:
To be added when I actually run a prod version of the bot.
## Config
Values you can include in `instance/config.py` to change how the bot behaves.
### Channel points interval and amount
Set the FLASK_APP variable:
```bash
export FLASK_APP=tlapbot
```
Using the flask debug server for running apps for non-development purposes is not recommended. Rather, you should be using a proper Python WSGI server.
On my own live owncast instance, I use gunicorn.
Install gunicorn (if you don't have it installed):
```bash
pip install gunicorn
```
Run the app (with gunicorn):
```bash
gunicorn -w 1 'tlapbot:create_app()'
```
**⚠️WARNING:** Because of the way the scheduler is initialized in the project,
I recommend running tlapbot with only one gunicorn worker. (`-w 1`)
If you use multiple workers, each worker sets up its own scheduler, and then users
get given points by each worker. (So running the app with `-w 4` means users get four times as many points than listed in the config.)
I'd like to fix this shortcoming of tlapbot at some point in the future (so that it can take advantage of extra workers), but for now it's broken like this.
## Configuration files
### config.py
Values you can include in `config.py` to change how the bot behaves.
(`config.py` should be in the instance folder: `/instance/config.py` for folder install, or `/[venv]/var/tlapbot-instance/config.py` for a `.whl` package install.)
#### Channel points interval and amount
`POINTS_CYCLE_TIME` decides how often channel points are given to users in chat,
in seconds.
`POINTS_AMOUNT_GIVEN` decides how many channel points users receive.
By default, everyone receives 10 points every 600 seconds (10 minutes).
### redeems.py
(`redeems.py` should be in the instance folder: `/instance/redeems.py` for folder install, or `/[venv]/var/tlapbot-instance/redeems.py` for a `.whl` package install.)