← Back to branch summary

~barry/mailman/events-and-web

« back to all changes in this revision

Viewing changes to src/mailman/docs/START.rst

 * Some additional documentation on related components such as Postorius and
   hyperkitty have been added, given by Stephen J Turnbull.

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/mailman/docs/START.rst
2
2
Getting started with GNU Mailman
3
3
================================
4
4
 
5
 
Copyright (C) 2008-2011 by the Free Software Foundation, Inc.
6
 
 
7
 
 
8
 
Alpha Release
9
 
=============
10
 
 
11
 
The Mailman 3 alpha releases are being provided to give developers and other
12
 
interested people an early look at the next major version.  As such, some
13
 
things may not work yet.  Your participation is encouraged.  Your feedback and
14
 
contributions are welcome.  Please submit bug reports on the Mailman bug
 
5
Copyright (C) 2008-2012 by the Free Software Foundation, Inc.
 
6
 
 
7
 
 
8
Beta Release
 
9
============
 
10
 
 
11
This is a beta release.  The developers believe it has sufficient
 
12
functionality to provide full services to a mailing list, but it is not ready
 
13
for production yet.  Interfaces and administration may differ substantially
 
14
from the alpha series, but changes should be incremental going forward from
 
15
beta 1.  Changes from the alpha series will be described in notes to the main
 
16
text.
 
17
 
 
18
The Mailman 3 beta releases are being provided to give developers and other
 
19
interested people an early look at the next major version, and site
 
20
administrators a chance to prepare for an eventual upgrade.  The core list
 
21
management and post distribution functionality is now complete.  However,
 
22
unlike Mailman 2 whose web interface and archives were tightly integrated with
 
23
the core, Mailman 3 exposes a REST administrative interface to the web,
 
24
communicates with archivers via decoupled interfaces, and leaves summary,
 
25
search, and retrieval of archived messages to a separate application (a simple
 
26
implementation is provided).  As of beta 1 the web interface and archiver are
 
27
still at an early stage of development.  As such, some things may not work.
 
28
 
 
29
Contributions are welcome.  Please submit bug reports on the Mailman bug
15
30
tracker at https://bugs.launchpad.net/mailman though you will currently need
16
31
to have a login on Launchpad to do so.  You can also send email to the
17
32
mailman-developers@python.org mailing list.
18
33
 
19
34
 
20
 
Using the Alpha
21
 
===============
 
35
Requirements
 
36
============
22
37
 
23
38
Python 2.6 or 2.7 is required.  It can either be the default 'python' on your
24
39
$PATH or it can be accessible via the ``python2.6`` or ``python2.7`` binary.
25
40
If your operating system does not include Python, see http://www.python.org
26
41
downloading and installing it from source.  Python 3 is not yet supported.
27
42
 
 
43
In this documentation, a bare ``python`` refers to the python used to invoke
 
44
``bootstrap.py``, which might be ``python2.6`` or ``python2.7``, as well as
 
45
the system ``python`` or an absolute path.
 
46
 
 
47
Mailman 3 is now based on the `zc.buildout`_ infrastructure, which greatly
 
48
simplifies building and testing Mailman.
 
49
 
 
50
During the beta program, you may need some additional dependencies, such as a
 
51
C compiler and the Python development headers and libraries.  You will need an
 
52
internet connection.  Also the `web UI`_ and `archive UI`_ are distributed and
 
53
installed separately.
 
54
 
28
55
 
29
56
Building Mailman 3
30
57
==================
31
58
 
32
 
Mailman 3 is now based on the `zc.buildout`_ infrastructure, which greatly
33
 
simplifies building and testing Mailman.
34
 
 
35
 
You do not need anything other than Python and an internet connection to get
36
 
all the other Mailman 3 dependencies.  Here are the commands to build
37
 
everything::
 
59
Here are the commands to build everything in core Mailman::
38
60
 
39
61
    % python bootstrap.py
40
62
    % bin/buildout
50
72
 
51
73
Build the online docs by running::
52
74
 
53
 
    % bin/docs
54
 
 
55
 
(You might get warnings which you can safely ignore.)  Then visit
56
 
 
57
 
    parts/docs/mailman/build/mailman/docs/README.html
 
75
    % python setup.py build_sphinx
 
76
 
 
77
(You might get warnings which you can safely ignore.)  Then visit::
 
78
 
 
79
    build/sphinx/html/README.html
58
80
 
59
81
in your browser to start reading the documentation.  Or you can just read the
60
82
doctests by looking in all the 'doc' directories under the 'mailman' package.
61
83
Doctests are documentation first, so they should give you a pretty good idea
62
 
how various components of Mailman 3 works.
 
84
how various components of Mailman 3 work.
63
85
 
64
86
 
65
87
Running Mailman 3
88
110
 * ``./mailman.cfg``
89
111
 * ``~/.mailman.cfg``
90
112
 * ``/etc/mailman.cfg``
 
113
 * ``argv[0]/../../etc/mailman.cfg``
91
114
 
92
115
Run the ``bin/mailman info`` command to see which configuration file Mailman
93
116
will use, and where it will put its database file.  The first time you run
102
125
now, all configuration happens via the command line and REST API.
103
126
 
104
127
 
 
128
Mailman Web UI
 
129
--------------
 
130
 
 
131
The Mailman 3 web UI, called *Postorius*, interfaces to core Mailman engine
 
132
via the REST client API.  It is expected that this architecture will make it
 
133
possible for users with other needs to adapt the web UI, or even replace it
 
134
entirely, with a reasonable amount of effort.  However, as a core feature of
 
135
Mailman, the web UI will emphasize usability over modularity at first, so most
 
136
users should use the web UI described here.
 
137
 
 
138
Postorius was prototyped at the `Pycon 2012 sprint`_, so it is "very alpha" as
 
139
of Mailman 3 beta 1, and comes in several components.  In particular, it
 
140
requires a `Django`_ installation, and Bazaar checkouts of the `REST client
 
141
module`_ and `Postorius`_ itself.  Building it is fairly straightforward,
 
142
however, given Florian Fuchs' `Five Minute Guide` from his `blog post`_ on the
 
143
Mailman wiki.  (Check the `blog post`_ for the most recent version!)
 
144
 
 
145
 
 
146
The List Archiver
 
147
-----------------
 
148
 
 
149
In Mailman 3, the archivers are decoupled from the core engine.  It is useful
 
150
to provide a simple, standard interface for third-party archiving tools and
 
151
services.  For this reason, Mailman 3 defines a formal interface to insert
 
152
messages into any of a number of configured archivers, using whatever protocol
 
153
is appropriate for that archiver.  Summary, search, and retrieval of archived
 
154
posts are handled by a separate application.
 
155
 
 
156
A new `archive UI`_ called Hyperkitty, based on the `notmuch mail indexer`_
 
157
and `Django`_, was prototyped at the PyCon 2012 sprint by Toshio Kuratomi, and
 
158
like the web UI it is also in early alpha as of Mailman 3 beta 1.  The
 
159
"hyperkitty" archiver is very loosely coupled to Mailman 3 core.  In fact, any
 
160
email application that speaks LMTP or SMTP will be able to use hyperkitty.
 
161
 
 
162
A `five minute guide to hyperkitty`_ is based on Toshio Kuratomi's README.
 
163
 
 
164
 
105
165
.. _`zc.buildout`: http://pypi.python.org/pypi/zc.buildout
106
166
.. _`lazr.config`: http://pypi.python.org/pypi/lazr.config
107
 
.. _`web ui`: https://launchpad.net/mailmanweb
 
167
.. _`Postorius`: https://launchpad.net/postorius
 
168
.. _`archive UI`: https://launchpad.net/hyperkitty
 
169
.. _`Django`: http://djangoproject.org/
 
170
.. _`REST client module`: https://launchpad.net/mailman.client
 
171
.. _`Five Minute Guide the Web UI`: WebUIin5.html
 
172
.. _`blog post`: http://wiki.list.org/display/DEV/A+5+minute+guide+to+get+the+Mailman+web+UI+running
 
173
.. _`notmuch mail indexer`: http://notmuchmail.org
 
174
.. _`five minute guide to hyperkitty`: ArchiveUIin5.html
 
175
.. _`Pycon 2012 sprint`: https://us.pycon.org/2012/community/sprints/projects/