================================
Getting started with GNU Mailman
================================

Copyright (C) 2008-2011 by the Free Software Foundation, Inc.


Alpha Release
=============

The Mailman 3 alpha releases are being provided to give developers and other
interested people an early look at the next major version.  As such, some
things may not work yet.  Your participation is encouraged.  Your feedback and
contributions are welcome.  Please submit bug reports on the Mailman bug
tracker at https://bugs.launchpad.net/mailman though you will currently need
to have a login on Launchpad to do so.  You can also send email to the
mailman-developers@python.org mailing list.


Using the Alpha
===============

Python 2.6 is required.  It can either be the default 'python' on your $PATH
or it can be accessible via the 'python2.6' binary.  See http://www.python.org
for details on getting Python 2.6.

Mailman 3 is now based on the `zc.buildout`_ infrastructure, which greatly
simplifies building and testing Mailman.

You do not need anything other than Python 2.6 and an internet connection
to get all the other Mailman 3 dependencies.  Here are the commands to
build everything::

    % python2.6 bootstrap.py
    % bin/buildout

Now you can run the test suite via::

    % bin/test

You should see no failures.

At this point you can read the doctests by looking in all the 'doc'
directories under the 'mailman' package.  Doctests are documentation
first, so they should give you a pretty good idea how various components
of Mailman 3 works.

What, you actually want to *run* Mailman 3?  Oh well, if you insist.  You
will need to set up a configuration file to override the defaults and set
things up for your environment.  Mailman is configured via the `lazr.config`_
package which is really just a fancy ini-style configuration system.

For now though, start by looking through ``src/mailman/config/schema.cfg``.
Create a file for your overrides; it can be called anything and can live
anywhere, but I like to call it ``mailman.cfg``.  For any value in
``schema.cfg`` you want to override, just add a section header (the
square-bracketed names) and then the key/value pair you want to override.

Mailman searches for its configuration file using the following search path.
The first existing file found wins.

 * ``-C config`` command line option
 * ``$MAILMAN_CONFIG_FILE`` environment variable
 * ``./mailman.cfg``
 * ``~/.mailman.cfg``
 * ``/etc/mailman.cfg``

Run the ``bin/mailman info`` command to see which configuration file Mailman
will use, and where it will put its database file.  The first time you run
this, Mailman will also create any necessary run-time directories and log
files.

Try ``bin/mailman --help`` for more details.  You can use the commands
``bin/mailman start`` to start the queue runner daemons, and of course
``bin/mailman stop`` to stop them.

There is no web u/i right now.  Contributions are welcome!


.. _`zc.buildout`: http://pypi.python.org/pypi/zc.buildout
.. _`lazr.config`: http://pypi.python.org/pypi/lazr.config