Welcome to the installation instructions for markive-tools.

The markive-tools package is discussed on the moto at 
list.standblue.net mailing list.  To subscribe, send a blank
email to moto-subscribe@list.standblue.net . 

-----------------------------------------------------------
                      Preinstallation
-----------------------------------------------------------

'markive-tools' is the peice of Markive that is responsible
for inserting messages into the database.  It is designed
to be run from .qmail files, but should work with just about
any other .forward, .courier, etc.  

Although markive-tools is a part of Markive, you do not need 
Moto to be installed to use markive-tools.  Moto is only 
needed if you want to run the web interface to the archive.

Ideally there should be a special system user that is only
used for inserting messages into the database, but this is
not a hard rule.  If you do decide to have a dedicated user
account for this purpose, I suggest creating an account with
the following properties:

 username:  markive
 home dir:  /var/spool/markive
 shell:     /bin/false

On Red Hat Linux systems you can use the following commands:
(as root)

 # useradd -M -d /var/spool/markive -s /bin/false markive
 # mkdir -m 700 /var/spool/markive
 # chown markive.markive /var/spool/markive

If you have similar instructions for other OS's I would love
to have them so I can include them here.

If you plan on running the insertion scripts as an existing
user then you do not need to create any accounts, just read
the next steps carefully.


-----------------------------------------------------------
                 Create Your Databases
-----------------------------------------------------------

Markive currently only supports MySQL, so you will need to
first create your database, and decide on the user.  Most
MySQL distributions come with a script, mysql_setpermission
that can be used to add new users and databases.  You can
also use the mysqladmin program that is a part of MySQL.
Which ever method you choose, be sure to add a completely 
separate database only for markive.  I recommend using the
name 'markive'. 

You will need the Python MySQLdb module, which is available
from SourceForge at the following URL:

  http://www.sourceforge.net/projects/mysql-python/

-----------------------------------------------------------
               Installing markive-tools
-----------------------------------------------------------

First, download the source tarball into a directory on your
system.  See http://projects.standblue.net/software/markive/ 
to get the tarballs.

Unpack the tarball:

 # tar xf markive-tools-XXX.tar.gz
 # gunzip markive-tools-XXX.tar
 # cd markive-tools-XXX/

At this point you will need to remember the database name,
username, and password that you created for Markive.  You 
will also need to decide on the home location of Markive. 
If you created a separate system user like I suggested above
then you will already have the home location.  If you are
going to run the markive-tools as a different user then you
may want to create a new directory for it:

 $ pwd
 /home/cwright/markive-tools-XXX
 $ mkdir /home/cwright/markive
 $ ./configure --prefix=/home/cwright/markive/

This will install markive-tools into /home/cwright/markive
with the scripts going in /home/cwright/markive/bin/ and 
the configuration files in /home/cwright/markive/etc/ .

The configure script takes several different optional 
arguments:

 $ ./configure --help
 options:
 --prefix=[install base]
 --dbhost=[hostname]
 --dbname=[database name]
 --dbuser=[db username]
 --dbpass=[db password]

Be sure to pass the database name, username and password to
the configure script, otherwise you need to manually adjust
the information in the markive-save.pl and addlist.sh scripts.

Once you have run configure then you are ready to install
the scripts.  Be sure to be a user who can install into the
necessary directories, that is, if you are going to install
into /var/spool/markive then be root, or some user that has
write priviledges to that directory.  Then, simply run the
'setup' script:

 # ./setup
 #

If you see no errors then everything went smooth and you now
have the markive-tools installed.  If you see errors then
check out the problem, fix it, and try again.

Thats all there is to it!


-----------------------------------------------------------
                   Archiving A List
-----------------------------------------------------------

To begin archiving a mailing list you first need to create
the list table in the database.  The addlist.sh script is
designed to do this for you.  Simply change directories to
where you installed markive-tools (--prefix=) and run the
following:

 # ./bin/addlist.sh listname
 #

Note that list names should not contain dashes (-), spaces,
or any other non alphanumeric characters.

Now that the table is created you need to create your .qmail
or .forward file to process the list:

 # echo '|/path/to/markive-save.py listname' > ~markive/.qmail-listname

Of course, if you arent running qmail, adjust this to fit
your MTA's supported method.  For .forward files with the
Postfix MTA you will need to quote the entire command:

 # echo '"|/path/to/markive-save.py listname"' > ~markive/.forward+listname

I would like input from others on how this is handled in other 
MTA's.  Please report your findings to the moto at list.standblue.net 
mailing list (see the top of this file for subscribing information).

Now all you need to do is subscribe this address to the list
you want to archive.