diff --git a/README.md b/README.md index 88a7b1f..a05c453 100644 --- a/README.md +++ b/README.md @@ -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`)