Merge branch 'wiki'

AdminGuide.wiki

@@ -0,0 +1,92 @@
+#summary How to administer a SubEtha system
+#labels Featured
+
+This document assumes you have read and understood the InstallGuide.
+
+<wiki:toc max_depth="2" />
+
+= Initial Administration =
+
+Do not forget to edit subetha.xml as described in the InstallGuide.
+
+= Concepts =
+
+If you are familiar with mailing list managers, SubEtha should be easy to master. The basic ideas are that:
+
+== User Accounts ==
+  * User accounts are created by subscribing to a mailing list with an email address.
+  * Each user account can have multiple email addresses.
+  * Each user account can have subscriptions to multiple lists, and designate which email address each list will deliver to.
+  * If a user is subscribed to a list (and has permission to post), email from any email address associated with that account will be accepted to the list.
+  * If a user with an existing account adds an email address that is already associated with another account, the two accounts are automatically and intelligently merged into a single account.
+  * Any time a user wishes to add a new email address to their account (either manually or by subscribing to a mailing list), a roundtrip confirmation using a token is required.
+  * Confirmation tokens are completely stateless; no changes are made on the server until the token is confirmed. If a token is lost or sent to the wrong address, simply repeat the add/signup process.
+  * Some accounts are designated as Site Administrators. In addition to the ability to create mailiing lists, site administrators have full permissions on all mailing lists.
+  * Only Site Administrators can grant or revoke the Site Administrator privilege.
+
+== Mailing Lists ==
+
+  * Mailing lists are created by Site Administrators.
+
+  * The list creator decides two critical pieces of information:
+    # The mailing list email address, which must be unique on the site. The entire address (including domain) is significant; thus announce@yourdomain.com and announce@otherdomain.com are different lists. Of course, DNS MX records must actually route this mail to the host that SubEtha is running on.
+    # The "official" public URL to the list's website, e.g. {{{http://www.yourdomain.com/announce}}}. This URL can be *any* URL that actually hits the SubEtha HTTP server and isn't already used by another list, including the root context (/).  You should also avoid lists that might conflict with SubEtha operation (eg, /list.jsp).  Note that like email addresses, URLs are domain-sensitive:  http://www.example1.com/ is a different list than http://www.example2.com/.
+
+  * Mailing lists have an arbitrary set of Roles, each of which have permissions such as POST and EDIT_FILTERS. The list owner decides what roles exist and what permissions they have. A permission is always relative to a list.
+
+  * Each list has a special Owner role which has all permissions on the list. The Owner role cannot be deleted or modified. Thus, at minimum, all lists have at least this one role.
+
+  * The list owner designates one role which will automatically be assigned to new list subscribers. This is the "default" role.
+
+  * The list owner designates one role which will be the effective role of any users who have not logged in. This is the "anonymous" role.
+
+  * To make it clear by way of example, a user visiting the archives page for a mailing list will be allowed to view the archives only if at least one of the following conditions is true:
+
+  * The user is logged in and the user is a site administrator.
+
+  * The user is logged in, the user is subscribed to the list, and the user's subscription role has permission VIEW_ARCHIVES.
+
+  * The user is not logged in and the special "anonymous" role has permission VIEW_ARCHIVES.
+        
+     Note that users who are not permitted to view list archives will not be displayed the View Archives menu item.
+
+== Moderation Holds ==
+
+  * List owners can configure a mailing list to hold all subscription requests for manual approval. When a subscription request arrives, notification is sent to all users who have permission to APPROVE_SUBSCRIPTIONS.
+
+  * Arriving messages can be held in two ways, HARD and SOFT.
+
+  * HARD holds require explicit moderator (anyone with APPROVE_MESSAGES permission) approval from the website. Only filters can trigger this type of hold, and moderators are notified via email when the message is held.
+
+  * SOFT holds occur when mail arrives to a list from an email address that does not have POST permission (ie, the address is associated with an account that lacks the permission or the address is not associated with a subscribed account and the special anonymous role for the list does not grant POST permission). SOFT holds can potentially be self-moderated in one of two ways.
+    # The email address is added to an account that is already subscribed, and that subscribed account has a role with POST permission. This would be the case when a subscribed user posts from a new email address, then adds the new address to their account.
+    # The poster subscribes the email address with a new account and the default role for the mailing list has POST permission.
+
+  Note that moderators are not notified via email about SOFT holds. Typically SOFT holds are spam. The poster is given sufficient instruction to properly self-moderate the hold (ie, subscribe to the list). In addition, no more than one "you must wait for admin approval" email per day will be sent to the poster. This will help prevent 'backscatter' related to spam.
+
+  * There is no specially designated "moderator" account. You either have the APPROVE_MESSAGES/APPROVE_SUBSCRIPTIONS permissions or you do not. List owners who wish to create special moderator-only accounts can create a "Moderator" role with only that permission; in fact several of the blueprints do exactly this.
+
+  * Generally speaking, moderators should check for subscription holds and ignore message holds (which will usually be spam). Non-spammers can self-moderate their own messages.
+
+== Bounce Processing ==
+
+  * SubEtha intelligently handles bounce messages using [http://en.wikipedia.org/wiki/VERP "VERP"]'d envelope senders. This removes the need to attempt to parse bounce messages from servers.
+
+  * The envelope sender is VERP'd and thus bounces cause the bounceCount to increment faster than decrement.
+
+  * It works like this:
+    # Every EmailAddress has a bounceCount.
+    # When a mail is sent from a list to an EmailAddress, the bounceCount is decremented by one (at most once per 24 hrs, even if multiple mails are sent within that period).
+    # When a bounce is received, the bounceCount is incremented by two (at most once per 24 hrs).
+    # The EmailAddress is removed from all lists (by setting subscription to "No Delivery") when the bounceCount reaches a threshold which is currently hard coded as 7.
+
+== Programming ==
+  Please see the ProgrammingGuide for more information.
+
+  * SubEtha is a true three-tiered application. Nearly everything you can do from the website can be automated using the remote Hessian interface. This interface is fully contained in core-api.jar.
+
+  * SubEtha offers two kinds of plugins.
+    # *Filters* manipulate email either as it arrives or as it is sent (or both). Each filter defines a set of configuration parameters that list owners can set on a per-list basis.  See DevelopingFilters.
+    # *Blueprints* initialize a new mailing list with a set of configuration options. This includes basic settings, enabled filters, filter arguments, roles, and permissions. No matter what blueprint a list is created with, list owners are free to reconfigure the list afterwards.
+
+  * Plugins run inside the SubEtha JVM and run with site administrator privilege. Technically this means they can do almost anything. We recommend you stick to the published APIs; any other API is considered internal and highly likely to change without notice.  On the other hand, we're not [http://www.apple.com/ dicks] and we actually like developers, so post to the [http://www.subethamail.org/dev Dev List] and we'll help you out either way.

ChangeLog.wiki

@@ -0,0 +1,146 @@
+#summary Changes between releases
+#labels Featured
+
+For specific instructions to upgrade between versions, see UpgradingVersions.
+
+= Changes =
+
+== 2.1 ==
+
+  * Major refactoring to the internal code to bring it current with the released version of CDI.
+  * List URLs can now be any URL that points to the SubEtha HTTP server.
+  * Replaced the Lucene direct-access code with Hibernate Search.
+  * Updated all third-party jars to modern versions.
+  * Fixed a longstanding bug deleting lists.
+  * A handful of miscellaneous bug fixes.
+
+Lots of internal changes, few external changes.  The most important change is that SubEtha now runs on the "current" version of Resin (>= 4.0.9).
+
+You will need to rebuild the fulltext index (from the Site Status page).  See UpgradingVersions.
+
+== 2.0 ==
+
+ * For 2.0, SubEtha was ported to Resin 4.0 (see WhyResin).
+ * Many architectural changes were made but very few features were added.
+ * We've moved to a new home at google code.
+
+ * Here are some of the changes to note:
+   * Added fallback smtp host for a new integration option
+   * Site admins can change user's names
+   * List owners can change subscribed user's names but only if the names are empty
+   * Updated libraries (Hibernate, Logging, SubethaSMTP)
+   * Updated packaging and docs
+   * Developed and tested on MySQL and PostgresSQL
+   * Allow "sent on behalf of" emails (ie. Sender: and From: are different)
+   * Denser encoding for shorter VERP envelope sender length
+   * Minor HTML changes on various pages.
+   * Added Hessian remote protocol support (removed "WS" remoting)
+   * Indexing and Cleanup start shortly after deployment, and periodically as before
+   * Much smaller memory footprint, and much quicker startup (20s on dev machines vs minutes for JBoss)
+
+If you are upgrading from a previous version, these changes *must* be
+made to the database (these are for MySQL, your database data types may be
+different):
+
+{{{
+  ALTER TABLE Mail CHANGE fromField sender TEXT;
+  ALTER TABLE Mail CHANGE envelopeSender senderNormal TEXT NOT NULL;
+}}}
+
+== 1.0.2 ==
+
+ * Workaround problem with building ear on JDK6 and deploying on JDK5.
+ * Updated Velocity from 1.4 to 1.5.
+ * Added integration documentation for Sendmail and Qmail.
+ * Include PlumberBean in order to allow mail-service.xml overrides for unit testing.
+ * Reverted URL redirection changes for proxied subetha installations.
+
+== 1.0.1 ==
+
+ * Fixed problem with the AppendFooterFilter not properly encapsulating the footer in multipart mime messages.
+ * Updated to JBoss 4.0.5.GA from the JEMS 1.2.0 GA installer.
+ * Ant build system has been rewritten from scratch.
+ * The ready-to-run (RTR) release is now based off a copy of JBoss that we maintain in our <a href="http://guest@subetha.tigris.org/svn/subetha/jboss/trunk/">svn repo
+ * Added a new filter mode for archive rendering (mail web view).
+ * Filter exceptions no longer stop processing of the message.
+ * Messages without subjects were throwing exceptions if the SubjectFilter was enabled.
+ * Added ability to download/export messages.
+ * UI tweaks and improvements.
+
+== 1.0 ==
+
+ * Fixed a bug rendering the permission error page.
+ * Fixed a problem unsubscribing from lists.
+
+== 0.9.6 ==
+
+ * Workaround for a major Hibernate bug introduced in JBoss 4.0.5.GA.
+
+== 0.9.5 ==
+
+ * Now expects JBoss 4.0.5.GA.
+ * The list of lists page should show # of subscribers and # of archived messages.
+ * Added the ability to post a new or reply to a message on a list via the web UI.
+ * Show confirmation screen when mass subscribing.
+ * Allow linefeed termination of emails when mass subscribing.
+
+== 0.9 ==
+
+ * Preliminary SOAP web service API exposed.
+ * Many minor UI improvements.
+ * Now works with the "new" JBoss 4.0.4.GA that has API change.
+ * Added small google adsense.
+ * The search indexer wasn't running properly.  It is now.
+ * The cleanup thread was not running properly.  It is now.
+ * Empty archive searches send a stack trace.
+ * UI for search results have been cleaned up. In addition, we now display the search score as a value from 1 to 10.
+ * Site admins can delete mailing lists.
+ * List admins can now delete messages from list archives.
+
+== 0.8 ==
+
+ * List administrators can now edit subscriber options.
+ * Administrator removal now works.
+ * Stabilized the order of many lists (subscriptions, email addresses, etc).
+ * "Your mail held" notifications now set at most once per day per sender address.
+ * Old held mail and held subscriptions are now periodically purged.
+ * Fixed a problem changing the postmaster address.
+ * Added $archiveUrl context variable to the AppendFooterFilter.
+ * You can now remove any email address as long as you have more than one.
+ * Various minor UI improvements.
+
+<strong>NOTE:</strong>  The names of some of the roles have changed.  You must update your database before SubEtha will function.  Shut down the JBoss instance running SubEtha and run the following queries:
+
+{{{	
+update RolePermission set perm='EDIT_SUBSCRIPTIONS' where perm='UNSUBSCRIBE_OTHERS'
+update RolePermission set perm='VIEW_ARCHIVES' where perm='READ_ARCHIVES'
+update RolePermission set perm='VIEW_NOTES' where perm='READ_NOTES'
+}}}
+
+
+== 0.7 ==
+
+ * Implemented fulltext searching for archives.
+ * Improved integration documentation.
+ * More UI cleanup.
+ * Several bugs fixed.
+
+<strong>NOTE:</strong>  The database schema changed slightly.  To upgrade from 0.6 or before, follow these instructions <strong>before deploying the new code</strong>.
+
+ * Shut down SubEtha.
+ * Rename column Mail.dateCreated to Mail.sentDate.
+ * Add column Mail.arrivalDate of same type as Mail.sentDate.
+ * update Mail set arrivalDate = sentDate
+ * Set Mail.arrivalDate to NOT NULL.
+
+== 0.6 ==
+ * Much internal refactoring.
+ * More useful information on list overview page.
+ * Archive threading cleaned up.
+ * User interface cleaned up.
+ * SMTP port now overridable with system property.
+ * Several bugs fixed.
+
+== 0.5 ==
+
+ * Initial release

CodingRules.wiki

@@ -0,0 +1,26 @@
+== SubEtha Coding Rules ==
+
+  * 4-space HARD tabs
+ Most editors do this by default.  Trust the defaults.
+  
+  * Pascal-like {} positions
+ Braces go on a line by themselves, outdented from their contents.
+
+{{{
+for (Object thing: collection)
+{
+	this.doSomething();
+}
+}}} 
+
+  * Use explicit references to  *this*
+ Refer to member variables and member methods:  this.doSomething(); This doesn't work when inner classes refer to member variables in outer classes, but it's a rare enough case that you can ignore this rule.
+			 
+  * No member variable prefix
+ Do not prefix member variables with a letter (ie, do not use mFoo). Just refer to it as this.foo in your code.
+			
+  * There is a space between if and (
+ For if, while, for, etc... there is a space between the statment and the (. ie: "if (", "while (", "for (".
+
+  * Code-as-literature
+ Code should read like English, and when it doesn't read like English, it should have comments that are written in English.  Be liberal with punctuation and grammar.  Somebody has to read this stuff.

DeploymentOptions.wiki

@@ -0,0 +1,25 @@
+= Resin Deployment Options =
+
+There are quite a few ways to deploy the subetha webapp in resin. These options are covered in more detail by the [http://caucho.com/resin/doc/webapp-deploy.xtp resin-docs].
+== war file in webapps ==
+This options results in the next option happening automatically, but only requires that you copy a single file into the webapps.
+
+== exploded webapp deployment ==
+This option requires you to deploy the war file as a directory in the same place.
+
+== versioned webapp ==
+This option allows multiple version to be deployed with the latest one in use. This could cause problems if the versions use a different database schema.
+
+[http://caucho.com/resin/doc/webapp-deploy.xtp#web-app%20versioning resin-docs]
+
+== hot-deployed webapp ==
+This option allows the application to be deployed across a cluster easily. In this case, special attention must be made to also deploy the configuration across the cluster (or at least each node in the cluster manually, if there are differences).
+
+This can be done with a resin ant-tasks, or via the resin-admin webapp, requires an administrator setup in resin, and the {{{<DeployService ...>}}} enabled in resin.xml.
+
+[http://caucho.com/resin/doc/webapp-deploy.xtp#Deploying%20to%20a%20live%20server%20without%20interruption resin-docs]
+
+== isolated webapp ==
+This options requires creating a new {{{<web-app-deployment ...>}}} in ${resin.dir}/conf/resin.xml.
+
+[http://caucho.com/resin/doc/webapp-deploy.xtp#Custom%20web-app%20with%20.war%20file resin-docs]