Mailman3 Suite for Debian
=========================

 This package ships a Django web project to provide the Mailman3 Postorius
web interface and the Hyperkitty web achiver together.

 After installing mailman3-web, a few remaining steps are required to get
a fully working Mailman3 suite:

 * The mail transport agent (MTA) needs to be configured to deliver list
   mail to mailman3. See /usr/share/doc/mailman3/README.Debian for further
   information.

 * The web server (either Apache or Nginx) needs to be configured. A snippet
   for Apache2 is included in /etc/mailman3/apache.conf, it may be included
   into Apache2 configuration (eg. default vhost) to serve mailman3-web upon
   installation. The Nginx file is a full vhost file that needs to be
   configured a little.  It is located in /etc/mailman3/nginx.conf, and may be
   modified in place.  Then, a symlink into /etc/nginx/sites-enabled and
   mailman3 will be ready.  Note that the Apache2 snippet and the Nginx
   configuration differ also in the available urls they provide. The Apache2
   snippet provides a /mailman3/ subdirectory as other sites may be present on
   the host. The Nginx file provides a standalone vhost, hence the /mailman3
   suburl is expendable and thus not present, except for aliasing static files.

 * The Hyperkitty configuration snippet needs to be added to the Mailman3
   configuration file at /etc/mailman3/mailman.cfg. This probably already
   has been done automatically during configuragion of the mailman3 package.
   If in doubt, reconfigure mailman3:

   # dpkg-reconfigure mailman3

 * A superuser for the Postorius web interface needs to be configured.
   This can be done during configuration of this mailman3-web package.
   If in doubt, reconfigure mailman3-web:

   # dpkg-reconfigure mailman3-web

   Alternatively, a superuser can be created with the following command:

   # django-admin createsuperuser --pythonpath /usr/share/mailman3-web \
       --settings settings --username <user> --email <mail-addr>


Database backend
================

 The default configured database backend is SQLite3. This is necessary to
not break automated (non-interactive) installations without installing
recommends.

 For productive setups, SQLite3 is *not* recommended as database backend.
PostgreSQL or MySQL should be used instead. The database configuration can
be automated by installing 'dbconfig-pgsql' or 'dbconfig-mysql' and running
'dpkg-reconfigure mailman3-web'. A respective local or remote database
server has to be available in this case.

 For MySQL as database backend, please read the next section.


MySQL database backend
======================

 Unfortunately, using MySQL as backend is broken with Debian MariaDB
packages between 10.0.22-2 and 10.2.7-1. The reason is that they use
'utf8mb4' as default character set but don't have 'dynamic' set as default
row format' along with InnoDB engine 'Barracuda' and 'innodb_large_prefix'
yet. This leads to 'Specified key was to long' errors at 'django-admin
migrate'.

 See Debian bug reports #891691[1], #886756[2] and upstream bug report
MDEV-14904[3] for further information.

 If you want to use MariaDB as database backend, you'll have to use
MariaDB 10.2 or newer for now. The issue is not fixed in MariaDB 10.1
packages yet as of March 1st 2018.

[1] https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=891691
[2] https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=886756
[3] https://jira.mariadb.org/browse/MDEV-14904


Detailed functionality of this package
======================================

 For information, the following things happen automated during
configuration of the package:

 * The database backend is prepared:
   * For SQLite3, an empty database file is created
   * For PostgreSQL/MySQL, database + user ('mailman3web') are created

 * A uWSGI daemon is enabled and started to provide the Django project
   via unix socket at `/run/mailman3-web/uwsgi.sock`.

 * A secure API token for the Hyperkitty archiver is generated and
   set both in the Django and in the Hyperkitty configuration.
   You might have to run `dpkg-reconfigure python3-mailman-hyperkitty`
   for `/etc/mailman3/mailman-hyperkitty.cfg` to have the correct API
   token configured.

 * The API password for the Mailman3 REST api is derived from
   `/etc/mailman3/mailman.cfg` and set accordingly in the mailman3-web
   configuration.

 * Optionally, supported webservers (currently Apache2) will be configured
   to provide access to the project at '/mailman3' (by reverse proxying
   to the uWSGI daemon). A Nginx configuration file is provided but it must be
   modified manually and set up into Nginx directories by hand.

 * Optionally, a superuser for the Postorius webinterface will be created.


 -- Jonas Meurer <jonas@freesources.org>, Sat, 10 Mar 2018 14:59:47 +0100
