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

readme update + add note about reverse proxy

Browse Source 
remove redundant install method, simplify wording
This commit is contained in:
Lili (Tlapka) 2022-11-15 14:56:24 +01:00
parent 07959e03ce
commit cf6202af3f
1 changed files with 33 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
README.md
View File

@ -7,23 +7,22 @@ to [Twitch channel points](https://help.twitch.tv/s/article/viewer-channel-point
[External actions](https://owncast.online/thirdparty/actions/).
## Features
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.
default, but the time interval and amount of points can be changed.
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.
You can configure redeems to fit your stream and the activities you're
doing.
The redeems then show on a "Redeems dashboard" that everyone can view
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.
This allows easy browsing of active challenges and recent redeems.
## Setup
Tlapbot requires Python 3, probably a fairly recent version of it too. (My live instance runs on Python 3.9.2.)
The Python prerequisites for running tlapbot are the libraries `flask`,
`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
@ -46,62 +45,53 @@ by default.)
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`,
In the Owncast web interface, navigate to the admin interface at `/admin`,
and then go to Integrations.
### Access Token
In Access Tokens, generate an Access Token to put in
In the Access Tokens tab, generate an Access Token to put in
`instance/config.py`. The bot needs both the "send chat messages" and "perform administrative actions"
permissions, since getting the list of all connected chat users is an administrator-only
action.
### Webhook
In webhooks, create a Webhook, and point it at your bot's URL with
In the webhooks tab, 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,
In debug, this will be something like `localhost:5000/owncastWebhook`. 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`.
to redirect Owncast traffic to your `localhost`.
### External Action
In External Actions, point the external action to your bot's URL with `/dashboard` added.
In debug, pointing the External Action to an address like `localhost:5000/dashboard` might not work because your localhost address doesn't provide https, which owncast requires.
**External Actions only work with https. Your server will need to support SSL and
https connections for this part to work.**
In development, a `localhost` address will not work with External Actions, since it doesn't provide https.
If you use [ngrok](https://ngrok.com/) to redirect Owncast traffic to localhost,
it will work because the ngrok connection is https.
**Example:**
**External Action config example:**
```
URL: MyTlapbotServer.com/dashboard
Action Title: Redeems Dashboard
```
#### Note about https and reverse proxying
Since External Actions require a secure https connection (for the tlapbot dashboard to work), you will need to set up a reverse proxy for tlapbot on your server. I'm not including a lot of information about it here, since I'm assuming you have some knowledge of the topic since you set up your own Owncast instance.
If you don't, the Owncast documentation about SSL and Reverse proxying is here: https://owncast.online/docs/sslproxies/
If your followed the [Owncast recommendation to use Caddy](https://owncast.online/docs/sslproxies/caddy/) you'd only need to include this in your caddyfile to make the tlapbot dashboard work:
```
MyTlapbotServer.com {
reverse_proxy localhost:8000
}
```
then MyTlapbotServer.com/owncastWebhook is the URL for webhooks,
and MyTlapbotServer.com/dashboard is the URL for the dashboard.
(And, obviously, you'd need to own the MyTlapbotServer.com domain, and have an A record pointing to your server's IP address.)
## Running the bot
### Running in debug:
Set the FLASK_APP variable:
@ -116,7 +106,7 @@ Run the app (in debug mode):
```bash
python -m flask --debug run
```
### Running in prod:
### Running in production:
Set the FLASK_APP variable:
```bash
export FLASK_APP=tlapbot
@ -133,6 +123,7 @@ 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`)