install.rst 4.7 KB
Newer Older
1 2 3
==================================
 Installing and running Mailman 3
==================================
Barry Warsaw's avatar
Barry Warsaw committed
4

Mark Sapiro's avatar
Mark Sapiro committed
5
Copyright (C) 2008-2018 by the Free Software Foundation, Inc.
Barry Warsaw's avatar
Barry Warsaw committed
6 7 8 9 10


Requirements
============

11 12 13
For the Core, Python 3.5 or newer is required.  It can either be the default
'python3' on your ``$PATH`` or it can be accessible via the ``python3.5`` or
``python3.6`` binary.  If your operating system does not include Python 3, see
14
https://www.python.org for information about downloading installers (where
15 16
available) and installing it from source (when necessary or preferred).
Python 2 is not supported by the Core.
Barry Warsaw's avatar
Barry Warsaw committed
17 18 19 20 21 22 23 24 25 26 27 28

You may need some additional dependencies, which are either available from
your OS vendor, or can be downloaded automatically from the `Python
Cheeseshop`_.


Documentation
=============

The documentation for Mailman 3 is distributed throughout the sources.  The
core documentation (such as this file) is found in the ``src/mailman/docs``
directory, but much of the documentation is in module-specific places.  Online
Danish Prakash's avatar
Danish Prakash committed
29
version of the `Mailman 3 Core documentation`_ is available.
Barry Warsaw's avatar
Barry Warsaw committed
30

Barry Warsaw's avatar
Barry Warsaw committed
31 32 33
Also helpful might be Mark Sapiro's documentation on `building out the
mailman3.org`_ server.

Barry Warsaw's avatar
Barry Warsaw committed
34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50

Get the sources
===============

The Mailman 3 source code is version controlled using Git. You can get a
local copy by running this command::

    $ git clone https://gitlab.com/mailman/mailman.git

or if you have a GitLab account and prefer ssh::

    $ git clone [email protected]:mailman/mailman.git


Running Mailman 3
=================

51 52 53 54 55 56 57 58 59 60 61
.. ATTENTION::
   The Mailman command line interface requires a properly configured UTF-8
   locale.  This is because the Core is implemented in `Python 3 and uses the
   click`_ command line argument parsing library.  Generally this will not be
   an issue since your shell is probably set up correctly.  However, in
   certain environments such as init scripts and cron scripts, your locale may
   not be UTF-8 compatible.  This can cause Mailman to mysteriously fail to
   run (since often, proper logging may also not be set up).  If you're seeing
   weird behavior in these types of environments, be sure they are UTF-8
   compatible, e.g. by setting ``export LANG=en_US.UTF-8``.

Barry Warsaw's avatar
Barry Warsaw committed
62 63
You will need to set up a configuration file to override the defaults and set
things up for your environment.  Mailman is configured using an "ini"-style
Barry Warsaw's avatar
Barry Warsaw committed
64 65 66
configuration system.  Usually this means creating a ``mailman.cfg`` file and
putting it in a standard search location.  See the :ref:`configuration
<configuration>` documentation for details.
Barry Warsaw's avatar
Barry Warsaw committed
67 68 69 70

By default, all runtime files are put under a ``var`` directory in the current
working directory.

Barry Warsaw's avatar
Barry Warsaw committed
71 72
Run the ``mailman info`` command to see which configuration file Mailman is
using, and where it will put its database file.  The first time you run this,
Barry Warsaw's avatar
Barry Warsaw committed
73 74 75 76 77 78
Mailman will also create any necessary run-time directories and log files.

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

Barry Warsaw's avatar
Barry Warsaw committed
79
Note that you can also run Mailman from one of the virtual environments
Barry Warsaw's avatar
Barry Warsaw committed
80 81
created by tox, e.g.::

Barry Warsaw's avatar
Barry Warsaw committed
82
    $ tox -e py35-nocov --notest -r
Barry Warsaw's avatar
Barry Warsaw committed
83 84 85 86 87 88 89 90 91 92
    $ .tox/py35-nocov/bin/mailman info


Mailman Shell
=============

This documentation has examples which use the Mailman shell to interact with
Mailman.  To start the shell type ``mailman shell`` in your terminal.

There are some testings functions which need to be imported first before you
Barry Warsaw's avatar
Barry Warsaw committed
93
use them.  They can be imported from the modules available in
Barry Warsaw's avatar
Barry Warsaw committed
94 95 96 97 98 99 100 101 102 103 104 105 106 107 108
``mailman.testing``.  For example, to use ``dump_list`` you first need to
import it from the ``mailman.testing.documentation`` module.

.. Of course, *this* doctest doesn't have these preloaded...
   >>> from zope.component import getUtility
   >>> from mailman.interfaces.listmanager import IListManager

The shell automatically initializes the Mailman system, loads all the
available interfaces, and configures the `Zope Component Architecture`_ (ZCA)
which is used to access all the software components in Mailman.  So for
example, if you wanted to get access to the list manager component, you could
do::

    $ mailman shell
    Welcome to the GNU Mailman shell
109 110 111
    Use commit() to commit changes.
    Use abort() to discard changes since the last commit.
    Exit with ctrl+D does an implicit commit() but exit() does not.
Barry Warsaw's avatar
Barry Warsaw committed
112 113 114 115

    >>> list_manager = getUtility(IListManager)


116
.. _`Python Cheeseshop`: https://pypi.org/
Barry Warsaw's avatar
Barry Warsaw committed
117 118
.. _`Mailman 3 Core documentation`: https://mailman.readthedocs.io
.. _`Zope Component Architecture`: https://pypi.python.org/pypi/zope.component
Barry Warsaw's avatar
Barry Warsaw committed
119
.. _`building out the mailman3.org`: https://wiki.list.org/DOC/Mailman%203%20installation%20experience
120
.. _`Python 3 and uses the click`: https://click.palletsprojects.com/en/7.x/python3/