README.md update: wording, prod install+running

also prepared headings for the config.py and redeems.py explainer

README.md

@@ -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
+This bot is currently in-development. The goal is to have an experience similar
-with Twitch channel points, while making use of Owncast webhooks and especially
+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
+The bot gives points to everyone in chat -- 10 points every 10 minutes by
-configured in the config, as well as the amount of points given.
+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
+The users in chat can then use their points on redeems -- rewards like "choose my
-only has one hardcoded redeem, but I'd like to make this configurable,
+background music", "choose what level to play next", "react to this video" etc.
-so that every Owncast streamer can set up their own redeems that best fit
+The streamer can configure redeems to fit their stream and the activity they're
-their stream.
+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 on the Owncast stream, or at its standalone URL.
-as an External action, a single button that displays information about
+This allows easy browsing of active challenges and recent redeems, for
-recent redeems.
+both the streamer and the viewers.
 ## Setup
 The Python prerequisites for running tlapbot are the libraries `flask`,
-`requests` and `apscheduler`.
+`requests` and `apscheduler`. If you follow the installation steps below,
-### Dev setup (from git repository)
+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.
+as a package in editable more.
-3. Initialize db:
+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.
+Set the FLASK_APP variable:
-## Config
+```bash
-Values you can include in `instance/config.py` to change how the bot behaves.
+export FLASK_APP=tlapbot
-### Channel points interval and amount
+```
+
+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.)