|
| 1 | +--- |
| 2 | +title: Home |
| 3 | +nav_order: 1 |
| 4 | +--- |
| 5 | +# ContextMod [](https://github.com/FoxxMD/context-mod/releases) [](https://opensource.org/licenses/MIT) [](https://hub.docker.com/r/foxxmd/context-mod) |
| 6 | + |
| 7 | +<img src="/logo.png" align="right" |
| 8 | +alt="ContextMod logo" width="180" height="176"> |
| 9 | + |
| 10 | +[**Context Mod**](https://contextmod.dev/) (CM) is an event-based, [reddit](https://reddit.com) moderation bot built on top of [snoowrap](https://github.com/not-an-aardvark/snoowrap) and written in [typescript](https://www.typescriptlang.org/). |
| 11 | + |
| 12 | +It is designed to help fill in the gaps for [automoderator](https://www.reddit.com/wiki/automoderator/full-documentation) in regard to more complex behavior with a focus on **user-history based moderation.** |
| 13 | + |
| 14 | +An example of the above that Context Bot can do: |
| 15 | + |
| 16 | +> * On a new submission, check if the user has also posted the same link in **N** number of other subreddits within a timeframe/# of posts |
| 17 | +> * On a new submission or comment, check if the user has had any activity (sub/comment) in **N** set of subreddits within a timeframe/# of posts |
| 18 | +> |
| 19 | +>In either instance Context Bot can then perform any action a moderator can (comment, report, remove, lock, etc...) against that user, comment, or submission. |
| 20 | +
|
| 21 | +Feature Highlights for **Moderators:** |
| 22 | + |
| 23 | +* Complete bot **autonomy**. YAML config is [stored in your subreddit's wiki](moderators/gettingStarted.md#setup-wiki-page) (like automoderator) |
| 24 | +* Simple rule-action behavior can be combined to create **complex behavior detection** |
| 25 | +* Support Activity filtering based on: |
| 26 | + * [Author criteria](subreddit-configuration/in-depth/filters/README.md#author-filter) (name, css flair/text, age, karma, moderator status, [Toolbox User Notes](https://www.reddit.com/r/toolbox/wiki/usernotes), and more!) |
| 27 | + * [Activity state](subreddit-configuration/in-depth/filters/README.md#item-filter) (removed, locked, distinguished, etc...) |
| 28 | + * State of Subreddit Activity is in [Subreddit](subreddit-configuration/in-depth/filters/README.md#subreddit-filter) (nsfw, name, profile, etc...) |
| 29 | +* Rules and Actions support [named references](subreddit-configuration/README.md#named-rules) -- **write once, reference anywhere** |
| 30 | +* Powerful [logic control](subreddit-configuration/advancedConcepts/flowControl.md) (if, then, goto) |
| 31 | +* [Delay/re-process activities](subreddit-configuration/README.md#dispatch) using arbitrary rules |
| 32 | +* [**Image Comparisons**](subreddit-configuration/imageComparison.md) via fingerprinting and/or pixel differences |
| 33 | +* [**Repost detection**](subreddit-configuration/in-depth/repost) with support for external services (youtube, etc...) |
| 34 | +* Event notification via Discord |
| 35 | +* [**Web interface**](#web-ui-and-screenshots) for monitoring, administration, and oauth bot authentication |
| 36 | +* [**Placeholders**](subreddit-configuration/actionTemplating.md) (like automoderator) can be configured via a wiki page or raw text and supports [mustache](https://mustache.github.io) templating |
| 37 | +* [**Partial Configurations**](subreddit-configuration/README.md#partial-configurations) -- offload parts of your configuration to shared locations to consolidate logic between multiple subreddits |
| 38 | +* [Guest Access](moderators/README.md#guest-access) enables collaboration and easier setup by allowing temporary access |
| 39 | +* [Toxic content prediction](subreddit-configuration/README.md#moderatehatespeechcom-predictions) using [moderatehatespeech.com](https://moderatehatespeech.com) machine learning model |
| 40 | + |
| 41 | +Feature highlights for **Developers and Hosting (Operators):** |
| 42 | + |
| 43 | +* [Server/client architecture](operator/serverClientArchitecture.md) |
| 44 | + * Default/no configuration runs "All In One" behavior |
| 45 | + * Additional configuration allows web interface to connect to multiple servers |
| 46 | + * Each server instance can run multiple reddit accounts as bots |
| 47 | +* Global/subreddit-level [**caching**](operator/caching.md) of Reddit APIs responses and CM results |
| 48 | +* [Database Persistence](operator/database.md) using SQLite, MySql, or Postgres |
| 49 | + * Audit trails for bot activity |
| 50 | + * Historical statistics |
| 51 | +* [Docker container](operator/installation.md#docker-recommended) and [docker-compose](operator/installation.md#docker-compose) support |
| 52 | +* Easy, UI-based [OAuth authentication](operator/addingBot.md) for adding Bots and moderator dashboard |
| 53 | +* Integration with [InfluxDB](https://www.influxdata.com) for detailed [time-series metrics](operator/database.md#influx) and a pre-built [Grafana](https://grafana.com) [dashboard](operator/database.md#grafana) |
| 54 | + |
| 55 | +# Table of Contents |
| 56 | + |
| 57 | +* [How It Works](#how-it-works) |
| 58 | +* [Getting Started](#getting-started) |
| 59 | +* [Configuration And Documentation](#configuration-and-documentation) |
| 60 | +* [Web UI and Screenshots](#web-ui-and-screenshots) |
| 61 | + |
| 62 | +### How It Works |
| 63 | + |
| 64 | +Each subreddit using the RCB bot configures its behavior via their own wiki page. |
| 65 | + |
| 66 | +When a monitored **Activity** (new comment/submission, new modqueue item, etc.) is detected the bot runs through a list of [**Checks**](subreddit-configuration/README.md#checks) to determine what to do with the **Activity** from that Event. Each **Check** consists of : |
| 67 | + |
| 68 | +#### Kind |
| 69 | + |
| 70 | +Is this check for a submission or comment? |
| 71 | + |
| 72 | +#### Rules |
| 73 | + |
| 74 | +A list of [**Rules**](subreddit-configuration/README.md#rules) to run against the **Activity**. Triggered Rules can cause the whole Check to trigger and run its **Actions** |
| 75 | + |
| 76 | +#### Actions |
| 77 | + |
| 78 | +A list of [**Actions**](subreddit-configuration/README.md#actions) that describe what the bot should do with the **Activity** or **Author** of the activity (comment, remove, approve, etc.). The bot will run **all** Actions in this list. |
| 79 | + |
| 80 | +___ |
| 81 | + |
| 82 | +The **Checks** for a subreddit are split up into **Submission Checks** and **Comment Checks** based on their **kind**. Each list of checks is run independently based on when events happen (submission or comment). |
| 83 | + |
| 84 | +When an Event occurs all Checks of that type are run in the order they were listed in the configuration. When one check is triggered (an Action is performed) the remaining checks will not be run. |
| 85 | + |
| 86 | +___ |
| 87 | + |
| 88 | +[Learn more about the RCB lifecycle and core concepts in the docs.](/README.md#how-it-works) |
| 89 | + |
| 90 | +## Getting Started |
| 91 | + |
| 92 | +#### Operators |
| 93 | + |
| 94 | +This guide is for users who want to **run their own bot on a ContextMod instance.** |
| 95 | + |
| 96 | +See the [Operator's Getting Started Guide](operator/gettingStarted.md) |
| 97 | + |
| 98 | +#### Moderators |
| 99 | + |
| 100 | +This guide is for **reddit moderators** who want to configure an existing CM bot to run on their subreddit. |
| 101 | + |
| 102 | +See the [Moderator's Getting Started Guide](moderators/gettingStarted.md) |
| 103 | + |
| 104 | +## Configuration and Documentation |
| 105 | + |
| 106 | +Context Bot's configuration can be written in YAML (like automoderator) or [JSON5](https://json5.org/). Its schema conforms to [JSON Schema Draft 7](https://json-schema.org/). Additionally, many **operator** settings can be passed via command line or environmental variables. |
| 107 | + |
| 108 | +* For **operators** (running the bot instance) see the [Operator Configuration](operator/configuration.md) guide |
| 109 | +* For **moderators** consult the [Subreddit Configuration Docs](subreddit-configuration/README.md) |
| 110 | + |
| 111 | +[**Check the full docs for in-depth explanations of all concepts and examples**](/docs) |
| 112 | + |
| 113 | +## Web UI and Screenshots |
| 114 | + |
| 115 | +### Dashboard |
| 116 | + |
| 117 | +CM comes equipped with a dashboard designed for use by both moderators and bot operators. |
| 118 | + |
| 119 | +* Authentication via Reddit OAuth -- only accessible if you are the bot operator or a moderator of a subreddit the bot moderates |
| 120 | +* Connect to multiple ContextMod instances (specified in configuration) |
| 121 | +* Monitor API usage/rates |
| 122 | +* Monitoring and administration **per subreddit:** |
| 123 | + * Start/stop/pause various bot components |
| 124 | + * View statistics on bot usage (# of events, checks run, actions performed) and cache usage |
| 125 | + * View various parts of your subreddit's configuration and manually update configuration |
| 126 | + * View **real-time logs** of what the bot is doing on your subreddit |
| 127 | + * **Run bot on any permalink** |
| 128 | + |
| 129 | + |
| 130 | + |
| 131 | +### Bot Setup/Authentication |
| 132 | + |
| 133 | +A bot oauth helper allows operators to define oauth credentials/permissions and then generate unique, one-time invite links that allow moderators to authenticate their own bots without operator assistance. [Learn more about using the oauth helper.](operator/addingBot.md#cm-oauth-helper-recommended) |
| 134 | + |
| 135 | +Operator view/invite link generation: |
| 136 | + |
| 137 | + |
| 138 | + |
| 139 | +Moderator view/invite and authorization: |
| 140 | + |
| 141 | + |
| 142 | + |
| 143 | +A similar helper and invitation experience is available for adding **subreddits to an existing bot.** |
| 144 | + |
| 145 | + |
| 146 | + |
| 147 | +### Configuration Editor |
| 148 | + |
| 149 | +A built-in editor using [monaco-editor](https://microsoft.github.io/monaco-editor/) makes editing configurations easy: |
| 150 | + |
| 151 | +* Automatic JSON or YAML syntax validation and formatting |
| 152 | +* Automatic Schema (subreddit or operator) validation |
| 153 | +* All properties are annotated via hover popups |
| 154 | +* Unauthenticated view via `yourdomain.com/config` |
| 155 | +* Authenticated view loads subreddit configurations by simple link found on the subreddit dashboard |
| 156 | +* Switch schemas to edit either subreddit or operator configurations |
| 157 | + |
| 158 | + |
| 159 | + |
| 160 | +### [Grafana Dashboard](operator/database.md#grafana) |
| 161 | + |
| 162 | +* Overall stats (active bots/subreddits, api calls, per second/hour/minute activity ingest) |
| 163 | +* Over time graphs for events, per subreddit, and for individual rules/check/actions |
| 164 | + |
| 165 | + |
| 166 | + |
| 167 | +## License |
| 168 | + |
| 169 | +[MIT](/LICENSE) |
0 commit comments