src/mailman/docs/START.rst

   1 .. _start-here:
   2
   3 ================================
   4 Getting started with GNU Mailman
   5 ================================
   6
   7 Copyright (C) 2008-2015 by the Free Software Foundation, Inc.
   8
   9
  10 Contact Us
  11 ==========
  12
  13 Contributions of code, problem reports, and feature requests are welcome.
  14 Please submit bug reports on the Mailman bug tracker at
  15 https://gitlab.com/mailman/mailman/issues (you need to have a login on Gitlab to
  16 do so).  You can also send email to the mailman-developers@python.org mailing
  17 list, or ask on IRC channel ``#mailman`` on Freenode.
  18
  19
  20 Requirements
  21 ============
  22
  23 For the Core, Python 3.4 or newer is required.  It can either be the default
  24 'python3' on your ``$PATH`` or it can be accessible via the ``python3.4``
  25 binary.  If your operating system does not include Python, see
  26 http://www.python.org for information about downloading installers (where
  27 available) and installing it from source (when necessary or preferred).
  28 Python 2 is not supported.
  29
  30 You may need some additional dependencies, which are either available from
  31 your OS vendor, or can be downloaded automatically from the `Python
  32 Cheeseshop`_.
  33
  34
  35 Documentation
  36 =============
  37
  38 The documentation for Mailman 3 is distributed throughout the sources.  The
  39 core documentation (such as this file) is found in the ``src/mailman/docs``
  40 directory, but much of the documentation is in module-specific places.  A
  41 prebuilt HTML version of `Mailman 3 documentation`_ is available at
  42 pythonhosted.org, as is `Postorius documentation`_.  `HyperKitty
  43 documentation`_ is available at ReadTheDocs.
  44
  45 The `Development Setup Guide`_ is a recent step-by-step explanation of
  46 how to set up a complete Mailman 3 system including the Mailman 3 core
  47 and basic client API, Postorius, and HyperKitty.
  48
  49 Testing Mailman 3
  50 =================
  51
  52 To run the Mailman test suite, just use the `tox`_ command::
  53
  54     $ tox
  55
  56 `tox` creates a virtual environment (virtualenv) for you, installs all the
  57 dependencies into that virtualenv, and runs the test suite from that
  58 virtualenv.  By default it does not use the `--system-site-packages` so it
  59 downloads everything from the Cheeseshop.
  60
  61 You do have access to the virtualenv, and you can use this to run individual
  62 tests, e.g.::
  63
  64     $ .tox/py34/bin/python -m nose2 -vv -P user
  65
  66 Use `.tox/py34/bin/python -m nose2 --help` for more options.
  67
  68 If you want to run the full test suite against the PostgreSQL database, set
  69 the database up as described in :doc:`DATABASE`, then create a `postgres.cfg`
  70 file any where you want.  This `postgres.cfg` file will contain the
  71 ``[database]`` section for PostgreSQL, e.g.::
  72
  73     [database]
  74     class: mailman.database.postgresql.PostgreSQLDatabase
  75     url: postgres://myuser:mypassword@mypghost/mailman
  76
  77 Then run the test suite like so::
  78
  79     $ MAILMAN_EXTRA_TESTING_CFG=/path/to/postgres.cfg tox -e pg
  80
  81 If you want to run an individual test against PostgreSQL, you would do it like
  82 so::
  83
  84     $ MAILMAN_EXTRA_TESTING_CFG=/path/to/postgres.cfg .tox/pg/bin/python -m nose2 -vv -P user
  85
  86 Note that the path specified in `MAILMAN_EXTRA_TESTING_CFG` must be an
  87 absolute path or some tests will fail.
  88
  89
  90 Building for development
  91 ------------------------
  92
  93 To build Mailman for development purposes, you can create a virtual
  94 environment outside of tox.  You need to have the `virtualenv`_ program
  95 installed, or you can use Python 3's built-in `pyvenv`_ command.
  96
  97 First, create a virtual environment (venv).  The directory you install the
  98 venv into is up to you, but for purposes of this document, we'll install it
  99 into ``/tmp/mm3``::
 100
 101     % pyvenv /tmp/mm3
 102
 103 Now, activate the virtual environment and set it up for development::
 104
 105     % source /tmp/mm3/bin/activate
 106     % python setup.py develop
 107
 108 Sit back and have some Kombucha while you wait for everything to download and
 109 install.
 110
 111 Build the online docs by running::
 112
 113     % python setup.py build_sphinx
 114
 115 If ``setup.py`` fails to recognize the ``build_sphinx`` command, then
 116 just install Sphinx in your virtualenv::
 117
 118     % pip install sphinx
 119
 120 This will automatically add the ``build_sphinx`` command to
 121 ``setup.py``, so just re-run the command.
 122
 123 Then visit::
 124
 125     build/sphinx/html/index.html
 126
 127 in your browser to start reading the documentation.  Or you can just read the
 128 doctests by looking in all the 'doc' directories under the 'mailman' package.
 129 Doctests are documentation first, so they should give you a pretty good idea
 130 how various components of Mailman 3 work.
 131
 132 Once everything is downloaded and installed, you can initialize Mailman and
 133 get a display of the basic configuration settings by running::
 134
 135     $ mailman info -v
 136
 137
 138 Running Mailman 3
 139 =================
 140
 141 What, you actually want to *run* Mailman 3?  Oh well, if you insist.  You will
 142 need to set up a configuration file to override the defaults and set things up
 143 for your environment.  Mailman is configured using an "ini"-style
 144 configuration system.
 145
 146 ``src/mailman/config/schema.cfg`` defines the ini-file schema and contains
 147 documentation for every section and configuration variable.  Sections that end
 148 in `.template` or `.master` are templates that must be overridden in actual
 149 configuration files.  There is a default configuration file that defines these
 150 basic overrides in ``src/mailman/config/mailman.cfg``.  Your own configuration
 151 file will override those.
 152
 153 By default, all runtime files are put under a `var` directory in the current
 154 working directory.
 155
 156 Mailman searches for its configuration file using the following search path.
 157 The first existing file found wins.
 158
 159  * ``-C config`` command line option
 160  * ``$MAILMAN_CONFIG_FILE`` environment variable
 161  * ``./mailman.cfg``
 162  * ``~/.mailman.cfg``
 163  * ``/etc/mailman.cfg``
 164  * ``argv[0]/../../etc/mailman.cfg``
 165
 166 Run the ``mailman info`` command to see which configuration file Mailman will
 167 use, and where it will put its database file.  The first time you run this,
 168 Mailman will also create any necessary run-time directories and log files.
 169
 170 Try ``mailman --help`` for more details.  You can use the commands
 171 ``mailman start`` to start the runner subprocess daemons, and of course
 172 ``mailman stop`` to stop them.
 173
 174 Postorius, a web UI for administration and subscriber settings, is being
 175 developed as a separate, Django-based project.  For now, the most flexible
 176 means of configuration is via the command line and REST API.
 177
 178
 179 Mailman Web UI
 180 --------------
 181
 182 The Mailman 3 web UI, called *Postorius*, interfaces to core Mailman engine
 183 via the REST client API.  It is expected that this architecture will make it
 184 possible for users with other needs to adapt the web UI, or even replace it
 185 entirely, with a reasonable amount of effort.  However, as a core feature of
 186 Mailman, the web UI will emphasize usability over modularity at first, so most
 187 users should use the web UI described here.
 188
 189
 190 The Archiver
 191 ------------
 192
 193 In Mailman 3, the archivers are decoupled from the core engine.  Instead,
 194 Mailman 3 provides a simple, standard interface for third-party archiving tools
 195 and services.  For this reason, Mailman 3 defines a formal interface to insert
 196 messages into any of a number of configured archivers, using whatever protocol
 197 is appropriate for that archiver.  Summary, search, and retrieval of archived
 198 posts are handled by a separate application.
 199
 200 A new archive UI called `Hyperkitty`_, based on the `notmuch mail indexer`_
 201 and `Django`_, was prototyped at the PyCon 2012 sprint by Toshio Kuratomi.
 202 The Hyperkitty archiver is very loosely coupled to Mailman 3 core.  In fact,
 203 any email application that speaks LMTP or SMTP will be able to use Hyperkitty.
 204
 205
 206 .. _`Postorius`: https://gitlab.com/mailman/postorius
 207 .. _`Hyperkitty`: https://gitlab.com/mailman/hyperkitty
 208 .. _`Django`: http://djangoproject.org/
 209 .. _`REST client module`: https://gitlab.com/mailman/mailmanclient
 210 .. _`Five Minute Guide the Web UI`: WebUIin5.html
 211 .. _`blog post`: http://wiki.list.org/display/DEV/A+5+minute+guide+to+get+the+Mailman+web+UI+running
 212 .. _`notmuch mail indexer`: http://notmuchmail.org
 213 .. _`five minute guide to Hyperkitty`: ArchiveUIin5.html
 214 .. _`Pycon 2012 sprint`: https://us.pycon.org/2012/community/sprints/projects/
 215 .. _`Python Cheeseshop`: http://pypi.python.org/pypi
 216 .. _`virtualenv`: http://www.virtualenv.org/en/latest/
 217 .. _`pyvenv`: https://docs.python.org/3/library/venv.html
 218 .. _`Mailman 3 documentation`: http://www.pythonhosted.org/mailman/
 219 .. _`Postorius documentation`: http://www.pythonhosted.org/postorius/
 220 .. _`HyperKitty documentation`: https://hyperkitty.readthedocs.org/en/latest/development.html
 221 .. _`Development Setup Guide`: https://fedorahosted.org/hyperkitty/wiki/DevelopmentSetupGuide
 222 .. _tox: https://testrun.org/tox/latest/