Move the LICENSE and README into a doc/ folder.

[mailshears.git] / doc / README

diff --git a/doc/README b/doc/README
new file mode 100644 (file)
index 0000000..1f06558
--- /dev/null
+++ b/doc/README
@@ -0,0 +1,74 @@
+1. What is it?
+
+Mailshears prunes leftover mail-stuff.
+
+If you manage your mail system through a database, deleting a user or
+domain from the database probably doesn't remove the physical mail
+files and directory structure. Other stuff can be left behind
+too. Mailshears helps you clean up.
+
+
+2. Requirements
+
+Right now, mailshears is targeted at one type of setup:
+
+  * You're either using PostfixAdmin[1], or your users, domains, and
+    aliases are stored using the PostfixAdmin schema. This wouldn't be
+    too hard to change; on the other hand, it's a good schema.
+
+  * You use Dovecot[2] as your mailstore. This is an optional plugin, but
+    if you use something else for your physical mail storage,
+    mailshears can't help you. I would of course accept patches
+    implementing new plugins.
+
+    In fact, at the moment, the "Dovecot" plugin doesn't really do
+    anything Dovecot-specific. It just specializes the Mailstore to
+    use a <domain>/<localpart> filesystem layout.  It would make a lot
+    of sense to make that configurable, and just call it a
+    FilesystemMailstore.
+
+  * You maybe use Roundcube[3] webmail. Another optional
+    plugin. Specifically, roundcube-0.7.2 is supported at the moment.
+
+
+3. Installation
+
+You put it in a directory somewhere, and run bin/mailshears. To make
+it do anything, you'll need to create a config file. The default is
+stored in mailshears.example.conf.yml; I suggest you copy that to
+$HOME/.mailshears.conf.yml and edit it to fit your environment.
+
+You'll probably want to set up a cron job to run it every once in a
+while.
+
+
+4. How it works
+
+Mailshears gets a list of users and domains from your PostfixAdmin
+database. It then delegates to the plugins. A plugin represents
+something that you would like to clean up. For example, the
+DovecotMailstore plugin represents the physical mail
+files/directories. The RoundcubeDb plugin represents a Roundcube SQL
+database.
+
+Each plugin knows how to get a list of its own users and domains. If
+there's a user or domain in the plugin list that isn't in the
+PostfixAdmin list, then mailshears knows that you've deleted that user
+or domain from the database. So, it asks the plugin to clean up.
+
+By default, it doesn't actually /do/ anything. There's a variable in
+the config file that you'll need to set before mailshears will touch
+your junk.
+
+
+5. How to report bugs
+
+Email them to me at michael@orlitzky.com.
+
+
+
+[1] http://postfixadmin.sourceforge.net/
+
+[2] http://dovecot.org/
+
+[3] http://www.roundcube.net/