This document explains how to install the forum-list bridge. This is very
much a work in progress. Read *everything* before beginning the setup.

1. Requirements:

* phpBB 3.0
* MySQL
* a mail server
* Perl
* PEAR modules: Mail, Log
* Perl modules: LWP::UserAgent, HTTP::Request::Common

2. Check out the bridge code from SourceForge:

  git clone git://vassalengine.git.sourceforge.net/gitroot/vassalengine/listbridge

(Note: The code is in the VASSAL repository at present because it was 
developed for VASSAL's forum. I will probably move it to its own repo
at some point.)

3. Two modifications need to be made to phpBB's posting.php to set up
the bridge in the forum-to-list direction. You can get the changes by
applying posting.patch to posting.php.

Note that after applying the patch, you'll need to modify the path in
each new require_once to match where you've put the bridge files.

4. For the list-to-forum direction, you need to set up an alias to receive
mail from your list. I'm using postfix, so I added this to my /etc/aliases:

forum-bridge:          "|/usr/local/lib/bridge/postfix_handoff.pl"

Here, forum-bridge should be whatever you want the bridge address to be named,
and the path you should adjust to wherever you put postfix_handoff.pl. (Mine
is where it is due to SELinux issues.) Adjust the URL in postfix_handoff.pl
as needed.

Then, subscribe your bridge address to your mailing list.

5. Bridge database: The bridge keeps a database which maps 

* Create a MySQL database, and populate it using src/schema.sql.

* Create a user for the DB, put the database name, username, and password
  into BridgeConf.php. (BridgeConfg.php.example is given as an example.)

* The posts table correlates phpBB post ids with email message ids. This
  table is filled as posts are made. There's nothing to configure here.

* The forums table maps each list address to the id of the forum which
  receives its messages by default. E.g., mine contains one row,
  
    'messages@vassalengine.org', 2
  
  This means that messages coming in from the mesages@vassalengine.org list
  which would start new threads on the forum will start those new threads in
  the forum with id 2. (Incoming messages which are part of existing threads
  are posted to those threads.) If I had more than one list in use, I could
  direct its new posts to forum 2, or some other forum, if I so chose.

* The lists table maps each forum id to the address of the list which
  receives its messages. I have forums with ids 2-9, so I have these
  eight rows:

    'messages@vassalengine.org', 2
    ...  
    'messages@vassalengine.org', 9

  E.g., this means that messages posted to the forum with id 3 are sent
  out to the messages@vassalengine.org list. (You could, in principle,
  direct posts in different forums to different lists; I just happen not
  to in my current setup.)

6. Configuration

* Set $php_root_path in PhpBB3Conf.php.

* $sender in forum_post_send.php should match the bridge address.

* The regex which strips the list footer in PhpBB3.php will need to be
  adjusted to match your list footer.

* $attach_dir in attachment_writer.php should match the storage directory
  for post attachments for your forum.

* grep for CONFIG_TODO, change the things

* Possibly some that I'm missing? Let me know.

7. TODO:

* Installation could be improved somewhat, e.g., by pulling all
  configuration data into one file.

* $sender and list footer should be configured per-list and pulled from
  the lists table.

* There are PHPUnit tests in test/. More tests should be written. All
  existing tests should pass, but don't at present.

  WARNING: DO NOT run the tests on a live forum, as they will blow away
  your phpbb_users table. 


Joel Uckelman
uckelman@nomic.net
1 March 2012