Hyperkittyのソースを表示

[[Category:Mail server]]
[[Category:Web applications]]
[https://gitlab.com/mailman/hyperkitty Hyperkitty] is a [[Django]] based archiver and archive interface for [[Mailman]].

== Installation ==

To use Hyperkitty, a working [[web server]] setup is required (e.g. using [[Apache HTTP Server]] to forward to the [[wikipedia:Wsgi|WSGI]] directly, or using [[Nginx]] forwarding requests to an application server such as [[UWSGI]]).

[[Install]] the {{Pkg|hyperkitty}} package.

{{Warning|Hyperkitty should only be accessed over [[TLS]] (unless only accessed directly from the machine running it for testing purposes), as it otherwise exposes passwords and user data to the network.}}

== Configuration ==

The web application is configured in {{ic|/etc/webapps/hyperkitty/settings_local.py}} (which is included by the default configuration in {{ic|/usr/share/webapps/hyperkitty/settings.py}}).

{{Note|Hyperkitty should store user sensitive data (e.g. sqlite database) in {{ic|/var/lib/hyperkitty/data/}}, as that directory is only accessible by root and the application itself.}}

Change the default secret for the application:

{{hc|/etc/webapps/hyperkitty/settings_local.py|2=
SECRET_KEY = <nowiki>'</nowiki>''something-very-secret''<nowiki>'</nowiki>
}}

Make sure to disable debugging when running in production:

{{hc|/etc/webapps/hyperkitty/settings_local.py|2=
DEBUG = False
}}

Add a valid email configuration (so that the [[Django]] application can verify subscribers):

{{hc|/etc/webapps/hyperkitty/settings_local.py|2=
EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
EMAIL_HOST = 'localhost'
EMAIL_PORT = 25
EMAIL_HOST_USER = ''username''
EMAIL_HOST_PASSWORD = ''password''
}}

{{Note|The {{ic|DEFAULT_FROM_MAIL}} and {{ic|SERVER_MAIL}} configuration options can be used to define the {{ic|From:}} header of mails sent for internal authentication and error reporting, respectively.}}

To connect with a running [[mailman]] instance's REST API, configuration options have to be added to hyperkitty's configuration.

{{hc|/etc/webapps/hyperkitty/settings_local.py|<nowiki>
MAILMAN_REST_API_URL = 'http://localhost:8001'
MAILMAN_REST_API_USER = 'rest_admin'
MAILMAN_REST_API_PASS = 'rest_admin_password'
</nowiki>}}

To configure the archive integration with a [[mailman]] instance first setup the  [[Mailman#Integrate with Hyperkitty|integration with hyperkitty]] on mailman's side and then configure hyperkitty to accept those connections:

{{hc|/etc/webapps/hyperkitty/settings_local.py|2=
MAILMAN_ARCHIVER_KEY = 'SecretArchiverAPIKey'
MAILMAN_ARCHIVER_FROM = ('127.0.0.1', '::1')
}}

The valid hosts or domain names for the application need to be defined:

{{hc|/etc/webapps/hyperkitty/settings_local.py|2=
ALLOWED_HOSTS = [
    'localhost',
    'lists.example.com'
]
}}

== Hosting ==

{{Expansion|Example for a setup using [[Apache HTTP Server]].}}

{{Note|
* Hyperkitty needs to be run as its own user and group (i.e. {{ic|hyperkitty}}). It is using {{ic|/etc/webapps/hyperkitty/}}, {{ic|/var/lib/hyperkitty/}} and {{ic|/run/hyperkitty/}} for configurations, static caches and (potentially) sockets, respectively.
* As the static files are by default served from a top-level {{ic|static/}} directory, which will conflict with [[postorius]] on the same (sub)domain, it is advisable to set the {{ic|STATIC_URL}} variable in {{ic|/etc/webapps/hyperkitty/settings_local.py}} to something unique (e.g. {{ic|'/hyperkitty_static/'}}).
}}

=== Nginx and uWSGI ===

Hyperkitty comes with a working [[uWSGI]] configuration file in {{ic|/etc/uwsgi/hyperkitty.ini}}.

[[Install]] {{Pkg|nginx}} and {{Pkg|uwsgi-plugin-python}}, create a per-application socket for [[uWSGI]] (see [[UWSGI#Accessibility of uWSGI socket]] for reference) and [[Systemd#Using units|activate]] the {{ic|uwsgi-secure@hyperkitty.socket}} unit.

For a local test setup, serving Hyperkitty at http://localhost/hyperkitty/ add the following [[Nginx]] configuration to your setup:

{{hc|/etc/nginx/hyperkitty.conf|<nowiki>
server {
  listen 80;
  server_name localhost;
  charset utf-8;
  client_max_body_size 75M;
  root /usr/share/webapps/hyperkitty;
  access_log /var/log/nginx/access.hyperkitty.log;
  error_log /var/log/nginx/error.hyperkitty.log;

  location /hyperkitty_static {
    alias /var/lib/hyperkitty/static;
  }

  location ~^/(hyperkitty|user-profile)/(.*)$ {
    include /etc/nginx/uwsgi_params;
    uwsgi_pass unix:/run/hyperkitty/hyperkitty.sock;
  }
}
</nowiki>}}

== Setup ==

{{Note| Run the following commands as the {{ic|hyperkitty}} user (e.g. using [[sudo]] or [[su]]).}}

After first installation make sure to generate a database:

 [hyperkitty]$ django-admin migrate --pythonpath /usr/share/webapps/hyperkitty/ --settings settings

Afterwards, the static data for the application needs to be collected:

 [hyperkitty]$ django-admin collectstatic --pythonpath /usr/share/webapps/hyperkitty/ --settings settings

To compress the data, run the following:

 [hyperkitty]$ django-admin compress --pythonpath /usr/share/webapps/hyperkitty/ --settings settings

[[Enable]] and [[start]] the {{ic|hyperkitty-qcluster.service}} [[systemd]] service for required asynchronous operations on the web application.

Populate the database with default data (when setting up for the first time):

 [hyperkitty]$ django-admin loaddata --pythonpath /usr/share/webapps/hyperkitty/ --settings settings first_start

Create a superuser account for the [[Django]] application:

 [hyperkitty]$ django-admin createsuperuser --pythonpath /usr/share/webapps/hyperkitty --settings settings

Log in to the admin interface of the [[Django]] application at http://localhost/hyperkitty/admin to be able to add more {{ic|Sites}} besides the default {{ic|example.com}} or to add additional {{ic|Mail domains}}.

{{Note|After adding a new {{ic|site}} make sure to set the {{ic|SITE_ID}} variable in {{ic|/etc/webapps/hyperkitty/settings_local.py}} to the respective ID!}}

== Tips and tricks ==

=== Importing mailman2 archives ===

Hyperkitty can import archives from mailman < 3.0.

{{Note|Run the following commands as the {{ic|hyperkitty}} user (e.g. using [[sudo]] or [[su]]).}}

 [hyperkitty]$ django-admin hyperkitty_import --pythonpath /usr/share/webapps/hyperkitty --settings settings -l ''ADDRESS'' ''mbox_file'' [''mbox_file'' ...]

Here {{ic|''ADDRESS''}} is the fully-qualified list name (e.g. {{ic|list@example.com}}) and the {{ic|''mbox_file''}} argument represents existing archives (in [[Wikipedia:Mbox|mbox]] format) to import (usually found in {{ic|/var/lib/mailman/archives/private/''LIST_NAME''.mbox/''LIST_NAME''.mbox}}).

Afterwards the full-text search index can be updated manually:

 [hyperkitty]$ django-admin update_index_one_list --pythonpath /usr/share/webapps/hyperkitty --settings settings ''ADDRESS''

{{Note|The full-text search index should be created by the minutely running cron-job automatically.}}

=== Content-Security-Policy Header ===

It is possible to define a [https://content-security-policy.com/ Content-Security-Policy] HTTP response header for HyperKitty. This allows content and resources only from specified locations.

When using [[nginx]] add the following to the {{ic|server}} directive in which HyperKitty is setup in:

{{hc|/etc/nginx/hyperkitty.conf|2=
[..]
add_header Content-Security-Policy "default-src 'self'; connect-src 'self'; img-src 'self' https://secure.gravatar.com; script-src 'self' 'unsafe-eval' 'unsafe-inline'; style-src 'self' 'unsafe-inline'";
[..]
}}

=== Disabling Gravatar support ===

The builtin [[Wikipedia:Gravatar (web service)|Gravatar]] support can be disabled in the configuration:

{{hc|/etc/webapps/hyperkitty/settings_local.py|2=
HYPERKITTY_ENABLE_GRAVATAR = False
}}

This option was introduced in Hyperkitty 1.3.4.  In earlier versions, use this instead:

{{hc|/etc/webapps/hyperkitty/settings_local.py|2=
GRAVATAR_SECURE_URL = '''''''
}}

=== Saving mail attachments to disk ===

By default Hyperkitty stores mail attachments in its database. However, it can be configured to save the attachments to disk instead:

{{hc|/etc/webapps/hyperkitty/settings_local.py|2=
HYPERKITTY_ATTACHMENT_FOLDER = /var/lib/hyperkitty/data/attachments
}}

{{Note|The location needs to be accessible and writable by the {{ic|hyperkitty}} user.}}

=== Template customization ===

Using [[Django]]'s [https://docs.djangoproject.com/en/3.0/ref/settings/#std:setting-TEMPLATES-DIRS TEMPLATES-DIRS] capabilities, it is possible to override the following templates to change the looks of the application:

* {{ic|hyperkitty/headers.html}}: the content will appear before the {{ic|</head>}} tag
* {{ic|hyperkitty/top.html}}: the content will appear before the {{ic|<body>}} tag
* {{ic|hyperkitty/bottom.html}}: the content will appear before the {{ic|</body>}} tag

=== Xapian search backend ===

Hyperkitty can make use of a Xapian based search backend. [[Install]] the {{Pkg|python-xapian-haystack}} package and configure the backend:

{{hc|/etc/webapps/hyperkitty/settings_local.py|2=
HAYSTACK_CONNECTIONS = {
    'default': {
        'ENGINE': 'xapian_backend.XapianEngine',
        'PATH': "/var/lib/hyperkitty/data/xapian_index",
    },
}
}}

Make sure to create the search index for all lists afterwards. Run the following command as the {{ic|hyperkitty}} user (e.g. using [[sudo]] or [[su]]):

 [hyperkitty]$ django-admin update_index --pythonpath /usr/share/webapps/hyperkitty --settings settings

== Troubleshooting ==

=== SMTP AUTH extension not supported by server ===

If upon first login with the admin user a {{ic|SMTNotSupportedError}} is thrown (logged to {{ic|/var/log/hyperkitty/hyperkitty.log}}), make sure to verify the {{ic|EMAIL_*}} settings in {{ic|/etc/webapps/hyperkitty/settings_local.py}}.

By default e.g. {{ic|EMAIL_USE_TLS}} is set to {{ic|False}} which might trigger a failed login via SMTP.

== See also ==

* [https://hyperkitty.readthedocs.io/en/latest/ Hyperkitty Documentation] - The upstream documentation
* [https://docs.mailman3.org/en/latest/ Mailman Suite Documentation] - The (high level) upstream documentation for the entire Mailman Suite (Mailman, Hyperkitty and Postorius)