Predator Alert Tool for Twitter - README

The Predator Alert Tool for Twitter is an add-on to your Web browser that enables you to subscribe to and view warnings about other Twitter users published by sources whose judgement you trust. It also enables you to create and optionally publish your own warnings, or "Predator Alerts," so you can share them with people who trust you.

The Predator Alert Tool for Twitter integrates cleanly into Twitter’s own Web interface. No separate app to use. Once installed, just use Twitter.com as you normally would.
You gain two new types of lists in addition to regular Twitter Lists: a “Twitter Blocklist” and any number of “warnlists.”
- Your Twitter Blocklist shows you all of the Twitter users you’ve blocked in one place.
- Your warnlists are where you publish your “Predator Alerts” and where you subscribe to Predator Alerts from others. If a tweet shows in any of your timelines from a user who is on a warnlist you’ve subscribed to, their tweet gets “redboxed.” In infamous Predator Alert Tool style, click through to that user’s profile to read details of each alert published about that user.
Unlike regular Twitter Lists, Twitter users can not remove themselves from Predator Alert Tool warnlists that you add them to, and taking a page from Predator Alert Tool for Facebook's book, you can add users you have blocked or users who have blocked you to warnlists that you make.
Subscribe to alerts from sources you trust. You always have the final say; as a fully decentralized system, unlike the Block Bot, this system offers no ability for others to moderate what you publish and thus it has a vastly reduced vulnerability to corruption by social cliques and their inevitable groupthink.

Overview

Unlike Twitter itself, Predator Alert Tool for Twitter is an unhosted Web app. This means that there isn't just one place where Predator Alerts are published, nor only one place to get a copy of the Predator Alert Tool for Twitter browser app. Instead, anyone who wants to can host their own "alert facilitator" (using software included in this package) to create and distribute alerts for their friends and community. Doing so also makes your website a distribution point of the Predator Alert Tool for Twitter browser add-on. Each facilitation server automatically generates the necessary customizations to the Predator Alert Tool for Twitter browser app that pairs it with the server that distributed it.

In other words, if you want to maintain a semi-private community warnlist, you or a friend can run your own such website for this purpose. This is called "running a facilitator." For more information about operating a Predator Alert Tool for Twitter facilitator, see Installing a facilitator.

System requirements

PAT Twitter user script (browser app)

The following software must be installed on your system before installing the Predator Alert Tool for Twitter user script.

Mozilla Firefox

If you use the Mozilla Firefox web browser (version 22 or higher), ensure you have the Greasemonkey extension installed (at version 1.0 or higher).

Google Chrome

If you use the Google Chrome web browser (version 29 or higher), ensure you have the Tampermonkey extension installed.

PAT Twitter facilitator server (website)

PostgreSQL 9.0 or higher
PHP 5.2 or higher
Web server, like Apache (2.0 or higher) or Lighttpd

Note that while MySQL is theoretically supported (through PEAR's MDB2 database abstraction layer), I've done no testing for that configuration. Testers and patches are welcome.

Try the PAT Twitter facilitator WordPress plugin, which does everything this code does, but should be easier to install for anyone familiar with how to install a WordPress plugin.

Installing a facilitator

The easiest way to set up your own Predator Alert Tool for Twitter facilitator is by deploying one to the Heroku cloud application platform. First, ensure you have git installed on your computer. Then, install the Heroku toolbelt.

Next, clone the Predator Alert Tool for Twitter repository and create a new Heroku app:

git clone https://github.com/fabacab/pat-twitter.git
cd pat-twitter
heroku apps:create

You'll need to tell Twitter about your new facilitator by creating a Twitter app in order to obtain a Twitter API key. For the purposes of Predator Alert Tool for Twitter, none of the information Twitter asks for makes any difference, so enter whatever you like.

Once you have your app's API key and API secret from Twitter, you can install them into your Predator Alert Tool for Twitter facilitator by setting them as environment variables:

heroku config:set TWITTER_CONSUMER_KEY=YOUR_API_KEY_HERE
heroku config:set TWITTER_CONSUMER_SECRET=YOUR_API_SECRET_HERE

Be sure you also check the box labelled "Allow this application to sign in with Twitter" to enable Sign in with Twitter. Also, in order to use some features of the Predator Alert Tool for Twitter facilitation server (such as the "Block users my friend blocks" function), you will need to grant your Twitter app "Read & write" permissions.

Predator Alert Tool for Twitter ships with an extremely simple template called "default." Activate it as follows:

heroku config:set PAT_TWITTER_THEME_FOLDER=default

If you want to change the look and feel of your facilitator, you can copy this template (located in the app's themes/ folder), modify it, and set the PAT_TWITTER_THEME_FOLDER environment variable to your new folder's name.

Next, provision a database for your facilitator:

heroku addons:add heroku-postgresql:dev

(Note that Heroku's free database tier has certain limitations. If you plan to run a fully public or popular Predator Alert Tool for Twitter facilitator, I recommend you move to a production-grade plan. Alternatively, you can run the server on most standard Web hosting plans.)

Finally, deploy your app to Heroku:

git push heroku master

You can navigate to your app by using the heroku open command. This should open your default browser and present you with a login screen.

Congratulations. You are now a Predator Alert Tool for Twitter facilitator. Share the URL of your app with anyone you want to and encourage them to break the silence around and cycle of abuse.

Updating a facilitator when new Predator Alert Tool for Twitter versions are released

New versions of the Predator Alert Tool for Twitter software will be tagged when they are generally available.

To update your facilitator to the latest available version:

cd WHEREVER_YOU_INSTALLED_PAT_TWITTER_EARLIER
git pull origin master
git push heroku master

To update your facilitator to a specific version, first fetch the changes from the repository, check out the tagged version, and redeploy that code. For instance, to update your facilitator to a (hypothetical) version "0.6.3" you would do the following:

cd WHEREVER_YOU_INSTALLED_PAT_TWITTER_EARLIER
git fetch origin             # Get the latest changes.
git checkout -b 0.6.3 0.6.3  # Check out a specific version on its own local branch.
git push heroku 0.6.3:master # Redeploy your app.

Updates to the Predator Alert Tool for Twitter may include updates to the browser app (userscript) or the facilitator itself, so you will need to update your facilitator when either component is updated.

fabacab / pat-twitter

readme