Documentation Outline

From FreeGreenTea

What is Lightning Bug (concise)


Table of contents
1 Installation Documentation

1.1 Requirements
1.2 Instructions

2 Under the Hood

2.1 Theory of Operation
2.2 Developers Guide

2.2.1 Database Schema
2.2.2 How we plug into external components

3 How To

3.1 Overview
3.2 Admin Guide

3.2.1 What are User Accounts

3.3 Pool Manager Guide
3.4 Vetter Guide
3.5 User Guide

4 Troubleshooting

4.1 Troubleshooting Issues

4.1.1 Gross Problems
4.1.2 Subtle Problems

4.2 FAQ

[edit]

Installation Documentation

[edit]

Requirements

This document lists and explains the different external tools that lightningbug relies on to function. Debian Linux package names are listed after requirements.

  • apache: (http://httpd.apache.org/) the web server that provides LB functionality. You could probably use a different web server, but some of the nice features (like short URLs) are designed with apache in mind. LightningBug has been successfully deployed on apache v 1.3.11 and apache 2.x. Debian packages: apache.
  • php4: (http://php.net/) PHP is the scripting language used by LightningBug. We developed the bulk of the functionality (up to LB v1.8.4) on Debian Sarge during the summer of 2004 so some versions of php older than 4.3.8 might not work. It has not been tested on PHP 5. We're using php as an apache module. PHP also needs to be compiled with support for mysql (database access) and gd2 (image manipulation). Debian packages: libapache-mod-php4, php4-mysql, php4-gd2.
  • ADOdb: (http://adodb.sf.net) We've used adodb to try to make LightningBug independent of the choice of backend database. This goal is not quite achieved, sadly, and LB is actually MySQL dependent. But work should continue in the DB-independence direction, and this seems like a decent platform for that goal. Debian packages: libphp-adodb or download from http://php.weblogs.com/.
  • MySQL (http://www.mysql.com) You may find it easier to install mysql-server and run your own mysql database server if you have full control over the host you are installing LightningBug on. Alternately, many providers will set you up with a database you can use directly. We were working with a MySQL server version 4.0.19 and later (4.0.21 at the moment). Older versions (especially 3.x) might have trouble with some of the queries we generate.
  • A working mail() function in php. The easiest way to do this is generally setting up a sendmail-style MTA interface. If you want your LightningBug installation to be able to send out e-mail (hint: you do!), you'll need to have a sendmail-style MTA installed on your system (assuming this is on a UNIX-style host, and not Windows). This is because LB uses the standard PHP mail() function to emit messages, which relies on sendmail or a drop-in replacement (see the PHP docs for mail(), which also discuss using external SMTP servers for mail() calls).
[edit]

Instructions

  1. Verify that your system has all of the required dependencies installed and working properly.
  2. Unpack a copy of the LB files somewhere in your filesystem readable by your web server (it doesn't have to be part of the web tree!). This can be done with a cvs checkout or by decompressing a tarball or something, depending on how you got the source. If you have downloaded the tarball, you can decompress it with: tar -xzvf lightningbug-xxx.tar.gz.
  3. Create a soft link somewhere in your web server's web tree which points to the /web directory in the LB sources. If your apache configuration doesn't follow symlinks, you should move the /web directory into your web tree and then create a soft link in the opposite direction. For example, if your web tree is in /var/www/ then execute: mv web /var/www/lightningbug followed by: ln -s /var/www/lightningbug web
  4. Get your database information (or create the database, if you are doing that yourself).
  5. If you are going to allow people to upload images, you need to decide on a directory in the filesystem for those images to be stored. This directory needs to be made writable by whatever user the web server is running as (www-data for debian's version of apache's httpd, for example).
  6. Copy /config.inc.php.sample to somewhere else (/config.inc.php is nice) and modify it to taste, including the database options. Each option should be fairly well-documented.
  7. Copy /web/index.php.sample to /web/index.php and change the paths in that file to match your installation.
  8. Import /docs/cc.sql into your database to build the initial DB structure needed.
  9. Create an admin user. At the moment, the only easy way to do this is to import /docs/test_user.sql, which creates a user with the name admin@example.org.
  10. You should then log in as that user and modify it to meet your requirements by going to index.php?action=resetpassword&vetter=1&limited_access_hash=LightningBx in your web browser relative to your new host information. For example, if you were creating a LightningBug installation in the /LB directory off of www.example.org, you would point your browser to: http://www.example.org/LB/index.php?action=resetpassword&vetter=1&limited_access_hash=LightningBx.
  11. When prompted, choose a new password for the admin user, set the admin's e-mail address to one that you can check, and change other settings for this user, such as Readable Name.
  12. Now, logged in as the admin user, you can create new boards, invite vetters, and you are up and running with LightningBug.
  13. If you want to change the default look, you should consider modifying /ihtml/header.ihtml, /ihtml/footer.ihtml, and /ihtml/sidebar.ihtml. Or you could try to integrate it into another content management system by modifying the cms_* variables in /config.inc.php.
[edit]

Under the Hood

Readable commentary about the theoretical basis of the software -- a developers guide

[edit]

Theory of Operation

Generally, how do things work.

[edit]

Developers Guide

[edit]

Database Schema

This is from the original index file: Very Rough Overview

Lightningbug relies on a php template class named Template which we subclassed with LB_Template -- this template class (provides sets of functions to generate good html from) integrates php classes with html templates. An "ihtml" file extension indicates a template file. Lightningbug provides a set of boards For each board (housing board, calendar, org board) a Abstractions Used to Interact with the Database

LB_AbstractDataObject (defined in library/base/class.lb.abstractdataobject.php) represents one or more rows of data in the database (but at most one row of any one table). (this could change in 2.0 -- see Mantis discussion bugs; we are considering getting rid of _datafields altogether) Each subclass of LB_AbstractDataObject is responsible for defining a _datafields member, which is a hash of field names to attributes of that field. It could also be described as a multi-dimensional array indexed by the field name (which is a string) and an array of attributes that apply to that field. (some subclasses are defined in library/[board|ban|vetter]/class.lb.*.php)

Available attributes are:

req 

   => (Is this field required? true or false)

pcre 

   => (Perl compatible regular expression -- only checked if variable exists)

explanation 

   => (Human readable explanation for pcre failure, e.g. "That doesn't even look like an e-mail address, fool.")

type 

   => (what form does this variable take? e.g. int, varchar, datetime)

fname 

   => (Human-readable description of the field, something like "Date Modified" or "Private E-mail")

key 

   => (Is this the key for this object? Exactly one field in any LB_AbstractDataObject must have the key set to true.)

no_user_set 

   => (Can a submit field alter the value of this field? true or false),

searchable 

   => (Is this field searchable, true or false),

tblname 

   => (What is the name of the table that this field appears in? A key may appear in multiple tables, in which case tblname will only mention one of them.)

The actual value of each field for a given object is stored in a member variable of the object. The name of that member variable is the same as the name of the _datafields element, but with a leading underscore.

Any subclass of LB_AbstractDataObject can define a function, _validateDerivedVars, which will further extend validation for that subclass, by handling validation not otherwise handled by the req and pcre attributes for the _datafields members. om the original index file:



[edit]

How we plug into external components


[edit]

How To

[edit]

Overview

(entry point for evaluation) Broadly explain how things work... Amanda will write this.


Lightning Bug is a thoughtful, secure system that allows anyone to submit an item to a bulletin board, but ensures that it will be reviewed before it is posted publicly. We built it because we weren't comfortable with the available tools to manage posts to www.CounterConvention.org, a website that we developed to coordinate and facilitate broad participation in protests of the Republican National Convention.

In its initial incarnation, Lightning Bug included a ride share board, a calendar, a housing board and a listing of organizations. At the request of the noRNC Clearinghouse, we added a board where note takers could post minutes.

If you are organizing a mass mobilization and want to use Lightning Bug, get in touch by writing to <a href="mailto:lightningbug-devel@lists.sourceforge.net">lightningbug-devel@lists.sourceforge.net</a> and we'd be glad to point you to a tarball and walk you through getting it set up. We hope to make a public release on or near April 2, 2005, but all kinds of things might get in the way of that goal.

[edit]

Admin Guide

Introductory admin guide (meant to be read by someone considering the software -- this is connected to the Developers guide, we aren't sure where "what are user accounts fits"

[edit]

What are User Accounts

There are three major roles for people who maintain the site: Vetter, Pool Manager, and Administrator.

  • Vetters make decisions about individual posts; every time something is posted to LightningBug, it is assigned to a vetter.
  • The vetters belong to pools, which are managed by pool managers. Pool managers are responsible for making sure that their pool is well staffed; they can invite people to become vetters, and they can remove vetters for malfeasance.
  • Administrators are responsible for general site administration, detailed below. This includes creating boards, customizing board settings, creating vetter pools, and identifying pool managers.

To take it from a different angle, generally an administrator will create a board. For the sake of this example, we'll say it's an Event Board. The administrator will then create a Vetter Pool for the Event Board (this same pool can be assigned to vet other boards as well), and add a Pool Manager. That Pool Manager will then invite vetters to the pool. Those vetters will then vet any postings to that board.

[edit]

Pool Manager Guide

A Pool Manager is responsible for a specific pool of vetters. At the level of the LightningBug software, this means that the pool manager can:

  • invite people to become vetters, or, if they are already vetters, can invite them to join the pool that the manager is responsible for;
  • toggle whether or not a vetter is receiving assignments, which is useful when a vetter is on vacation, in jail, or otherwise indisposed; and
  • remove vetters from the pool they manage (eg, for malfeasance, because they no longer wish to vet, etc.)

At a social level, Pool Managers are generally responsible for:

  • creating site policy;
  • training vetters to use LightningBug, as well as training them on site policy;
  • enforcing vetter policies; and
  • ensuring that vetters act in a timely manner

LightningBug has been designed to ensure that pool managers do not need to be computer experts; they need only be comfortable with a small set of forms. It is probably more important that they be good at communicating with their vetters, offering strong training and both positive and negative feedback.

[edit]

Vetter Guide

Vetters are the backbone of LightningBug. Every time a post is submitted, edited, or flagged, a vetter has to decide whether or not the post should be visible. Vetters belong to pools, which is how they receive their assignments. They also have a limited amount of time to deal with a post that's been assigned to them; the default time is 2 days. If the vetter isn't able to vet the post in that amount of time, the post is escalated and the entire vetter pool is called in to make a decision about it.

Upon receiving an assignment or escalation, a vetter has seven options:

  1. Approve. The post is approved and made live; the poster is notified.
  2. Reject. The post is rejected; the poster is notified of the reason for the rejection.
  3. Discard. The post is rejected; the poster is not notified.
  4. Request More Info. If the post does not quite fit the posting guidelines, if the vetter is unsure about some aspect of the post, or if the post omits key information, the vetter can request more information from the poster. The poster will then be sent and email with the vetter's concerns and link to edit the post.
  5. Escalate. If the vetter is uncomfortable or unable to vet a post, the vetter can escalate it, which will allow anyone in the vetter pool to vet the post.
  6. Ask For Help. If the vetter would like the input of other pool members on a post, but would like to retain the ability to make the final decision on a post, the vetter can ask for help. Other vetters in the pool are then invited to make comments on the post in order to help the assigned vetter determine whether or not to approve the post.
  7. Comment. The vetter's comments are made available to other vetters, but not shared with the poster. This is a mechanism that allows vetters to communicate their thoughts on a specific post to one another.

For escalated posts (ie, posts that belong to the entire pool, rather than a specific vetter), one more option exists:

  1. Claim It. The vetter will now be the assigned vetter of the post, but the vetter does not have to make a decision about the post immediately.

A good vetter need not be very technically saavy; the bulk of the work a vetter does is interpretting the site posting guidelines and communicating with their fellow vetters and people who have taken the time to post. Good vetters also tend to check their email with frequency.

[edit]

User Guide


User Guide

Lightningbug exists to allow authenticated users to submit content to a site.

In most cases this is content to be published to the site like a Calendar Event listing.
Sometimes the content is submitted just to be brought to the attention of one of the site 

maintainers like a question. After submitting the content the authenticated user will be

contacted by a vetter (somebody who makes a decision on the submitted content) letting the
user know the results of their submission.

User Experience For Submitting Content:

  1. User clicks on a link to submit content. This can either be a stand-alone link or a link on the page displaying all other approved submitted content.
  2. User is asked to submit a private email address (never to be displayed on the site.) Users will have to enter an email address they have access to as this email account will serve as the authentication method. Users do not "create" accounts, instead they confirm actions by following links in emails.
  3. After submitting their private email address the will see the form for submitting the content for the particular board (a board hosts multiple listings of a particular type, i.e. events, organizations, notes.)
  4. After submitting the content form, a preview page will be loaded that will display the content as if the content was approved and published to the site. Directly below the content there will be a button that will allow the user to go back to editing. And below that will be a text box and a submit button which will trigger the confirmation email to be sent to the user (see next step.) The text box will allow the user to add a note to their submission so the site maintainer vetting their post will have extra information on which to base their decision.
  5. If the user submitted their content in the above step, they will receive a confirmation email in their private email account. In this email is a link, if the user clicks on this email the site will treat the user as authenticated and assign the post to a vetter. The user will be informed their content was successfully submitted and will be reviewed by a vetter.
  6. After the time required for the vetter to make the decision, the user will receive an email informing them of the decision of their submission. The decision will be one of the following:
    • Approval
    • Required fields will vary depending on the listing, however, in all cases an e-mail to be used for verification (by default private, optionally publicly available) will be required.
    • On submit, e-mail address will be checked to make sure it has been filled in and appears valid. In addition, depending on the listing type, other fields will be checked to make sure they exist. If any checks fail, poster is returned to form and instructed to do a better job following directions.
    • If all fields are valid:
      • They will see a message on the web page telling them to check their e-mail account for directions on how to complete the process. The web page will display the e-mail address that they entered and warn them that if they didn't receive an e-mail message that they should check to make sure they typed their e-mail address properly and resubmit their request if they did not. The info@counterconvention.org e-mail address will listed if they have any questions.
      • The e-mail sent to the poster will contain a link (short enought so it doesn't break in the message) to a web page that they need to click on in order to confirm their listing. This link will be valid for three days (a cron job will regularly search and destroy unconfirmed entries). When they follow the link, the web page will say that their listing has been received and, if approved by a human being, it will be posted to the site. It will also say that the general turn-around time is 12 - 48 hours.
      • At this point, the poster may not be able to edit the posting. They just have to sit and wait.
      • Next, four possible things may happen:
        1. The poster receives an e-mail stating that their listing has been posted and it will also include the info@counterconvention.org e-mail address if they have any questions. In addition, it will give a link for modifying posts (this link will also be available on the main site). If the poster clicks on the link:
          • They will be prompted to enter their e-mail address
          • If the address is on file, that will generate a message which reads approximately: "You have just been sent an e-mail with instructions for editing your posts on the counter convention site. Please contact info@counterconvention.org if you don't get that e-mail. You must use this link within the next 2 hours or it will expire (at which point you will need to re-submit your request to get a new e-mail sent)."
          • The e-mail sent to the poster should include a list of editing links to all postings (one for each) she has on each of the various boards. The listing will include the status of each posting (confirmed or pending poster input). She picks the link for the listing that needs to be edited and uses it.
          • She gets a form allowing her to modify the listing - if she does not change her e-mail address, then the changes are automatically reflected on the site. If she does change her e-mail address, then she gets a web page saying that she needs to check her e-mail to confirm the new e-mail address. After checking her e-mail and clicking on the confirmation URL, the posting goes live.
          • If that address isn't in the database, error should read "sorry, that isn't in the database, maybe retype, maybe try another address?"
        2. The poster receives an e-mail stating that their listing was received but doesn't appear to be valid. It will include a message written by the vetter explaining what is missing or weird. It will include a web link that they can click on in order to modify their listing (this is the same link as in the edit listing example above).
          • Same process as above (click link to modify posting, get e-mail with list of current posts - one of which is labelled "pending poster input").
          • But, when modifying her listing she is not allowed to change her e-mail address at this point (only for simplicity sake). After making her changes, the web pages states that her changes have been recorded and that a human will review them in the next 12 to 48 hours.
        3. The poster receives an e-mail stating that their listing was rejected for reasons x, y, and z.
        4. The poster never hears from us again because their posting was silently deleted because it was obviously abusive.

      </ol>

      Vetter interface


      Overview: A vetter is a person who has been given a username and password on the system for the purpose of reviewing posts by posters to make sure they are legit.



      There are tier-one vetters and tier two vetters. Following are the ways a vetter can mark a posting:

      • Approve (tier one or tier two)
      • Defer - if they are unsure what to do with the posting and want feedback from other vetters (tier one or tier two)
      • Suggest rejection (tier one only)
      • Request more info - if it seems valid but they just didn't give enough info (tier two only)
      • Reject with message to poster - added in good faith but just doesn't fit the bill (tier two only)
      • Reject without message - silent delete abusive posting (tier two only)

      The purpose of tier-one vetters is to allow volunteers to join the process even if we don't know them that well. By giving them a job that they can't abuse we can easily get them involved without a big risk. After they have proven themselves, they can be promoted to tier-two vetters.

      Postings will not be sent to a vetters e-mail list. Instead, a round-robyn style list will be setup so that the first posting will go to one vetter, the next posting to the next vetter on the list and so on. This process will reduce the amount of traffic going to each vetter and also make the vetter more likely to respond when they get an e-mail (since they know it will depend on them to respond). If a vetter doesn't respond to a post in 12 hours, then it will be sent to the next person on the list.

      Each vetter post will contain a brief description of the listing plus a link to a web site. The link will be formed based on the vetter's username. When they click on the link they will be prompted for a password. If they have been assigned more than one listing, then all listing that they have not responded to will be listed on the page. The page will also contain a link to a list of criteria to be used when reviewing posts.

      All actions will be logged with the name of the vetter and comments.

      Vetter options and responses:

      1. Vetters will have the option to enter comment text explaining their decision. Optional for all posts except for deferred posts in which case it is required.
      2. If rejected or approved, the listing will disappear from the vetter's interface.
      3. If deferred it will become automatically assigned to all vetters. An e-mail will be sent to all vetters listing the request, including the comments as to why they chose to defer it. The vetters group can then discuss and learn from the experience.
      4. If suggest rejection is chosen, then the request is forwarded round robin style to the next available tier two vetter. It will disappear from the original vetter's interface.
      5. If "Request for more info" is selected, then the vetter will be prompted to enter a message to be sent via e-mail to the poster. The e-mail will automatically have included a canned message with a link that they can click on to modify their post.
      6. There will be an option to set all listings to reject with one click (if we get flooded with bogus requests).
      User interface


      Overview: A user is a person who is surfing the site and wants to alert us to bad postings.



      All listings on the site have a link called "flag this post." If a user clicks on the link they are prompted to choose from a drop down list of reasons for the flag (innacurate, violates posting guidelines, other) and a text field to enter more information. After submiting this information they receive a message thanking them for being a good samaritan and informing them that a human being will review the post in 12 to 48 hours.
      [edit]

      Troubleshooting

      [edit]

      Troubleshooting Issues

      You've installed LightningBug, and you're running into problems. Here are some things that might help you track down the problem.

      [edit]

      Gross Problems

      • is php installed?

      If, on trying to view lightningbug, you get a page which looks something like 

      <?php
/* lightningbug file: /index.php
this is the main gateway for the site.  no other pages will ever be
presented to the end user via http except for some images (in the
images/ directory) and some scripts (in the scripts/ directory).
you should copy over this file to index.php and modify it so that it
includes the correct paths for your installation.
*/
// Change the paths below to match the paths to your config file and
// your library.
require_once('/home/whatever/src/lightningbug/config.inc.php');
require_once('/home/whatever/src/lightningbug/library/base/main.php');
lb_main();
?>

      It means that your web server isn't passing the lightningbug source to a php interpreter, but instead feeding it out to the client. Read the documentation for your web server, or ask your web host provider, about how to direct it to interpret php files.

      • Which version of php?

      We haven't tested lightningbug against all versions of php. We developed it against versions 4.3.8, 4.3.9, and 4.3.10. We've placed some versioning checks into the code to make sure things work, but it's sparse. if you are running a more recent version of php, you are less likely to have problems...

      • Check your php configuration path

      LightningBug assumes that the current directory ('.') is in php's path. If it is not, you can get errors like: 

       Fatal error: main(): Failed opening required 'template.php' (include_path='')

      If this is happening, you can try to fix it with a call to ini_set('include_path', '.'); at the top of web/index.php, but this is a crufty fix. Ask whoever is maintaining your php installation to include '.' in the php initialization file.

      • Are your configuration files set up correctly?

      Many pervasive cryptic errors about files not being found (e.g. failed to open stream: No such file or directory in /var/www/ccdemo/web/index.php on line 17) are due to broken paths in web/index.php. You need to set those paths correctly according to the location of your installation.

      You may also want to review the settings in config.inc.php, which should be fairly well-commented.

      • can you connect to your database?

      You need a MySQL database to get lightningbug to work properly. If the database connection fails for some reason, you will probably get a page that looks something like this: 

      Warning:  mysql_connect(): Can't connect to local MySQL server through socket '/var/run/mysqld/mysqld.sock' (2) in /usr/share/adodb/drivers/adodb-mysql.inc.php< on line 338
	LightningBug installation is currently down
	Your LightningBug Installation is currently down, due to database issues.
	Please contact site-admin@example.org if you think it should be working.

      If you run into this problem, you should check that the variables in config.inc.php which start with db_... are set correctly. Check with your web host provider about the correct settings for your database.

      If you have command-line access to mysql, you can try connecting to it directly: mysql -u username -h hostname -p dbname

      This will prompt you for a password, and (if the information is correct), it should leave you with a mysql prompt.

      If this doesn't work, your database settings are wrong, or your database is not configured correctly.

      [edit]

      Subtle Problems

      If you've gotten past the gross problems, the following bits of advice might help you narrow down the problems:

      • Forcing error notification to browser

      config.inc.php has a line that sets the error reporting level. uncomment the error_reporting(E_ALL); line to get basic error messages sent to the web browser.

      • looking in lb_error_log

      Most errors are logged to the database in the table named lb_error_log. If you have direct access to the database, you can review the most recent error with the following sql command: SELECT * FROM lb_error_log ORDER BY date_entered DESC LIMIT 1;

      Also, you can coax a few more items to go into this log by setting define ('LB_DEBUG', true); in config.inc.php. Unfortunately, there is no way to view the contents of the lb_error_log through the web interface at this time.

      • Running the sanity check

      If you log into a LightningBug installation as an admin user, one of the available links in the navigation bar will be the "Sanity Check". If you click this link, it will do a relatively intensive scan of the database for items which seem misconfigured or out of place. While it's not completely exhaustive, it does provide a heads-up for things that might go wrong in the future.

      [edit]

      FAQ

      What is a pool?
      What is a board?
      What is a vetter?
      How do I add/remove a board?
      How do I add/remove a user?
      How do I add/remove a vetter?
      Can I install/administer lightningbug via ftp?
      How does lightningbug interact with my content management system?
      Why is it called "lightningbug"?
      I'm getting these weird messages. What should I do?
      Warning: main(class.lb.lightningbug.php): failed to open stream: No such file or directory in /home/sites/site50/users/adminnycsf/src/lightningbug/library/base/main.php on line 6
      Fatal error: main(): Failed opening required 'class.lb.lightningbug.php' (include_path Insert non-formatted text here='') in /home/sites/site50/users/adminnycsf/src/lightningbug/library/base/main.php on line 6

      I'm getting these weird messages. What should I do?
      Warning: main(template.php): failed to open stream: No such file or directory in /home/sites/site50/users/adminnycsf/src/lightningbug/library/base/class.lb.te mplate.php on line 6
      Fatal error: main(): Failed opening required 'template.php' (include_path='') in /home/sites/site50/users/adminnycsf/src/lightningbug/library/base/class.lb.te mplate.php on line 6