Added pre-release stuff.

git-svn-id: https://vassalengine.svn.sourceforge.net/svnroot/vassalengine/site-src/trunk@7048 67b53d14-2c14-4ace-a08f-0dab2b34000c

1 files changed, 89 insertions, 0 deletions

diff --git a/INSTALL b/INSTALL
new file mode 100644
index 0000000..e1b5395
--- /dev/null
+++ b/INSTALL
@@ -0,0 +1,89 @@
+This document explains how to install the forum-list bridge. This is very
+much a work in progress.
+
+1. Check out the bridge code from SourceForge:
+
+  svn co https://vassalengine.svn.sourceforge.net/svnroot/vassalengine/site-src/trunk/bridge
+
+(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.)
+
+2. 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.
+
+3. 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.
+
+4. 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.)
+
+5. Other adjustments:
+
+* 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.
+
+6. 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
+29 July 2010
+