diff options
| -rw-r--r-- | README.rst | 11 | ||||
| -rw-r--r-- | src/mailman/docs/ArchiveUIin5.rst | 96 | ||||
| -rw-r--r-- | src/mailman/docs/START.rst | 109 | ||||
| -rw-r--r-- | src/mailman/docs/WebUIin5.rst | 111 |
4 files changed, 309 insertions, 18 deletions
diff --git a/README.rst b/README.rst index 186062e53..d4095e687 100644 --- a/README.rst +++ b/README.rst @@ -38,6 +38,17 @@ Table of Contents src/mailman/docs/DATABASE src/mailman/docs/MTA src/mailman/docs/8-miles-high + src/mailman/docs/WebUIin5 + src/mailman/docs/ArchiveUIin5 + +Mailman modules +--------------- + +These documents are generated from the doctest suite. + +.. toctree:: + :glob: + src/mailman/bin/docs/* src/mailman/commands/docs/* src/mailman/database/docs/* diff --git a/src/mailman/docs/ArchiveUIin5.rst b/src/mailman/docs/ArchiveUIin5.rst new file mode 100644 index 000000000..b66b0b220 --- /dev/null +++ b/src/mailman/docs/ArchiveUIin5.rst @@ -0,0 +1,96 @@ +Set Up the Archive UI in Five Minutes +===================================== + +The Hyperkitty application aims at providing an interface to visualize +and explore mailman archives. + +This is a `django`_ project. + +Requirements +------------ + +- A mail archive in `maildir format`_ (no, you don't need a running + Mailman 3!) Eventually Hyperkitty will support `mbox format`_ for + backward compatibility with *pipermail*, and *zipped maildirs* seem + like a good idea to save space. **Beware:** Although you'd think + that we would be able to manipulate the venerable *mbox* format + safely and efficiently, that doesn't seem to be the case. *Maildir* + archives are **strongly** preferred, because they are more robust to + program bugs (whether in Mailman, hyperkitty, or in the originating + MUA!) +- `Django`_ is the web framework that supports the UI. +- `bunch`_ DOES WHAT? +- The `notmuch mail indexer`_ is used to generate indices (and + requires `Xapian`_). +- `Hyperkitty`_ itself, which is a UI, and not responsible for + maintaining the message archive itself. (Since the archive is in + `maildir format`_, any modern MTA or MDA can build one for you.) + + +Get it running (under virtualenv): +---------------------------------- + +It is generally a good idea to use `virtualenv`_ to create a stable +environment for your Python applications. + +- Create the virtualenv:: + + virtualenv mailman3 + +- Activate the virtualenv:: + + cd mailman3 + source bin/activate + +You don't *have* to use virtualenv, though, and if you don't want to, +just omit the preceding steps. Continue with + +- Install django and dependencies:: + + easy_install django + easy_install bunch + +- Install notmuch -- these are bindings that come with the notmuch C library. + The easiest way is probably to install them for your OS vendor and then + symlink them into the virtualenv similar to this:: + + yum install -y python-notmuch + +- Note: on a multiarch system like Fedora, the directories may be lib64 rather + than lib on 64 bit systems. Next:: + + cd lib/python2.7/site-packages + ln -s /usr/lib/python2.7/site-packages/notmuch . + +- Note: this is the version of notmuch I tested with; others may work:: + + ln -s /usr/lib/python2.7/site-packages/notmuch-0.11-py2.7.egg-info . + +- Install the hyperkitty sources:: + + git clone http://ambre.pingoured.fr/cgit/hyperkitty.git/ + +Running hyperkitty +------------------ + +- Start it:: + + cd hyperkitty + +- Put the static content where it should be:: + + python manage.py collectstatic + +- Run the Django server:: + + python manage.py runserver + + +.. _`hyperkitty`: https://launchpad.net/hyperkitty +.. _`Django`: http://djangoproject.org/ +.. _`notmuch mail indexer`: http://notmuchmail.org +.. _`bunch`: http://pypi.python.org/pypi/bunch +.. _`Xapian`: PLEASE-REPORT-MISSING-URL +.. _`maildir format`: PLEASE-REPORT-MISSING-URL +.. _`mbox format`: PLEASE-REPORT-MISSING-URL +.. _`virtualenv`: PLEASE-REPORT-MISSING-URL diff --git a/src/mailman/docs/START.rst b/src/mailman/docs/START.rst index ab2717956..d0122175c 100644 --- a/src/mailman/docs/START.rst +++ b/src/mailman/docs/START.rst @@ -2,39 +2,62 @@ Getting started with GNU Mailman ================================ -Copyright (C) 2008-2011 by the Free Software Foundation, Inc. +Copyright (C) 2008-2012 by the Free Software Foundation, Inc. -Alpha Release -============= +Beta 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 +This is a beta release. The developers believe has sufficient functionality +to provide full services to a mailing list, but it is not ready for +production yet. Interfaces and administration may differ substantially from +the alpha series, but changes should be incremental going forward from beta +1. Changes from the alpha series will be described in notes to the main +text. + +The Mailman 3 beta releases are being provided to give developers and other +interested people an early look at the next major version, and site +administrators a chance to prepare for an eventual upgrade. The core list +management and post distribution functionality is now complete. However, +unlike Mailman 2 whose web interface and archives were tightly integrated +with the core, Mailman 3 exposes a RESTful adminstrative interface to the +web, communicates with archivers via LMTP (or SMTP), and leaves summary, +search, and retrieval of archived messages to a separate application (a +simple implementation is provided). As of beta 1 the web interface and +archiver are still at an early stage of development. As such, some things +may not work. + +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 -=============== +Requirements +============ Python 2.6 or 2.7 is required. It can either be the default 'python' on your $PATH or it can be accessible via the ``python2.6`` or ``python2.7`` binary. If your operating system does not include Python, see http://www.python.org downloading and installing it from source. Python 3 is not yet supported. - -Building Mailman 3 -================== +In this documentation, a bare ``python`` refers to the python used to invoke +``bootstrap.py``, which might be ``python2.6`` or ``python2.7``, as well as +the system ``python`` or an absolute path. 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 and an internet connection to get -all the other Mailman 3 dependencies. Here are the commands to build -everything:: +all the other Mailman 3 dependencies. (N.B. In early betas this is something +of a lie, as the `web UI`_ and `archive UI`_ are distributed and installed +separately.) + + +Building Mailman 3 +================== + +Here are the commands to build everything in core Mailman:: % python bootstrap.py % bin/buildout @@ -50,16 +73,18 @@ You should see no failures. Build the online docs by running:: - % bin/docs + % python setup.py build_sphinx +[In the alphas we used ``bin/docs``, but this does not exist now.] (You might get warnings which you can safely ignore.) Then visit - parts/docs/mailman/build/mailman/docs/README.html + build/sphinx/html/README.html -in your browser to start reading the documentation. Or you can just read the +in your browser to start reading the documentation. [In the alphas this was +parts/docs/mailman/build/mailman/docs/README.html.] Or you can just 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. +how various components of Mailman 3 work. Running Mailman 3 @@ -102,6 +127,54 @@ The `web ui`_ is being developed as a separate, Django-based project. For now, all configuration happens via the command line and REST API. +Mailman Web UI +-------------- + +The Mailman 3 web UI is somewhat coupled to core Mailman via the "RESTful" +client API. It is expected that this architecture will make it possible for +users with special needs to adapt the web UI, or even replace it entirely, +with a reasonable amount of effort. However, as a core feature of Mailman, +the web UI will emphasize usability over modularity at first, so most users +should use the web UI described here. It may not be trivial to use a +different web UI. + +The Mailman web UI was prototyped at the PyCon 2012 sprint, so it is "very +very alpha" as of Mailman 3 beta 1, and comes in several components. In +particular, it requires a `Django`_ installation, and Bazaar checkouts of the +`REST client module`_ and the `web ui`_ itself. Building it is fairly +straightforward, however, given Florian Fuchs' `Five Minute Guide` from his +`blog post`_ on the Mailman wiki. (Check the `blog post`_ for the most +recent version!) + + +The List Archiver +----------------- + +Experience with Mailman 2's "pipermail" archiver has demonstrated that it is +unnecessary for the archiver to be tightly coupled to core Mailman, and that +it is useful to provide a simple, standard interface for third-party +archiving tools and services. For this reason, Mailman 3 uses the standard +mail transport protocols LMTP and SMTP to forward posts to archivers after +processing for list distribution. Summary, search, and retrieval of archived +posts are handled by a separate application. + +A new `archive UI`_ called Hyperkitty, based on the `notmuch mail indexer`_ +and `Django`_, was prototyped at the PyCon 2012 sprint by Toshio Kuratomi, +and like the web UI it is "very very alpha" as of Mailman 3 beta 1. Unlike +the web UI (and Mailman 2's default "pipermail" archiver), the "hyperkitty" +archiver is very loosely coupled to Mailman 3 core. In fact, any email +application that speaks LMTP or SMTP will be able to use hyperkitty, and +Mailman 3 can use any archiver that accepts posts via LMTP or SMTP. + +A `five minute guide to hyperkitty`_ is based on Toshio Kuratomi's README. + .. _`zc.buildout`: http://pypi.python.org/pypi/zc.buildout .. _`lazr.config`: http://pypi.python.org/pypi/lazr.config .. _`web ui`: https://launchpad.net/mailmanweb +.. _`archive UI`: https://launchpad.net/hyperkitty +.. _`Django`: http://djangoproject.org/ +.. _`REST client module`: https://launchpad.net/mailman.client +.. _`Five Minute Guide the Web UI`: WebUIin5.html +.. _`blog post`: http://wiki.list.org/display/DEV/A+5+minute+guide+to+get+the+Mailman+web+UI+running +.. _`notmuch mail indexer`: http://notmuchmail.org +.. _`five minute guide to hyperkitty`: ArchiveUIin5.html diff --git a/src/mailman/docs/WebUIin5.rst b/src/mailman/docs/WebUIin5.rst new file mode 100644 index 000000000..42a2f3e3c --- /dev/null +++ b/src/mailman/docs/WebUIin5.rst @@ -0,0 +1,111 @@ +Set Up the Mailman UI in Five Minutes +===================================== + +This is a quick guide to set up a development environment to work on +Mailman 3's web UI. If all goes as planned, you should be done within +5 minutes. This has been tested on Ubuntu 11.04. + +In order to download the components necessary you need to have the +Bazaar VCS installed on your system. Mailman and mailman.client need +at least Python version 2.6. + +It's probably a good idea to set up a virtual Python environment using +`virtualenv`_. `Here is a brief HOWTO`_. + +.. _`virtualenv`: PLEASE-REPORT-MISSING-URL +.. _`Here is a brief HOWTO`: ./ArchiveUIin5.html#get-it-running-under-virtualenv + + +GNU Mailman 3 +------------- + +First download the latest revision of Mailman 3 from launchpad. +:: + + $ bzr branch lp:mailman + +Install and test:: + + $ cd mailman + $ python bootstrap.py + $ bin/buildout + $ bin/test + +If you get no errors you can now start Mailman:: + + $ bin/mailman start + $ cd .. + +At this point Mailman will not send nor receive any real emails. But +that's fine as long as you only want to work on the components related +to the ReST client or the web ui. + + +mailman.client (the Python bindings for Mailman's ReST API) +----------------------------------------------------------- + +Download from launchpad:: + + $ bzr branch lp:mailman.client + +Install in development mode to be able to change the code without +working directly on the PYTHONPATH. +:: + + $ cd mailman.client + $ sudo python setup.py develop + $ cd .. + + +Django >= 1.3 +------------- + +The web ui is a pluggable Django application. Therefore you need to +have Django (at least version 1.3) installed. +:: + + $ wget http://www.djangoproject.com/download/1.3.1/tarball/ -O Django-1.3.1.tar.gz + $ tar xzf Django-1.3.1.tar.gz + $ cd Django-1.3.1 + $ sudo python setup.py install + $ cd .. + + +mailmanweb +---------- + +:: + + $ bzr branch lp:mailmanweb + $ cd mailmanweb + $ sudo python setup.py develop + + +Start the development server +---------------------------- + +:: + + $ cd dev_setup + $ python manage.py syncdb + $ python manage.py runserver + +The last command will start the dev server on http://localhost:8000. + +A note for MacOS X users (and possibly others running python 2.7) +----------------------------------------------------------------- + +*Note: These paragraphs are struck-through on the Mailman wiki.* + +On an OS X 10.7 (Lion) system, some of these steps needed to be +modified to use python2.6 instead of python. (In particular, bzr is +known to behave badly when used python2.7 on OS X 10.7 at the moment +-- hopefully this will be fixed and no longer an issue soon.) + +You will need to install the latest version of XCode on MacOS 10.7, +which is available for free from the app store. If you had a previous +version of XCode installed when you upgraded to 10.7, it will no +longer work and will not have automatically been upgraded, so be +prepared to install again. Once you have it installed from the app +store, you will still need to go run the installer from /Applications +to complete the installation. |