Jump to content
From ArchWiki

Postorius is a Django based management interface for Mailman.

## Installation

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

Install the postorius package.

Warning: Postorius 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 `/etc/webapps/postorius/settings_local.py` which is included by the default configuration in `/usr/share/webapps/postorius/settings.py`.

Note: Postorius should store user sensitive data (e.g. sqlite database) in `/var/lib/postorius/data/`, as that directory is only accessible by root and the application itself.

Change the default secret for the application:

    /etc/webapps/postorius/settings_local.py

    SECRET_KEY = 'something-very-secret'

Make sure to disable debugging when running in production:

    /etc/webapps/postorius/settings_local.py

    DEBUG = False

To be able to configure a running mailman instance configuration options for its REST API have to be added to postorius' configuration.

    /etc/webapps/postorius/settings_local.py

    MAILMAN_REST_API_URL = 'http://localhost:8001'
    MAILMAN_REST_API_USER = 'rest_admin'
    MAILMAN_REST_API_PASS = 'rest_admin_password'

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

    /etc/webapps/postorius/settings_local.py

    EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
    EMAIL_HOST = 'localhost'
    EMAIL_PORT = 25
    EMAIL_HOST_USER = username
    EMAIL_HOST_PASSWORD = password

Note: The `DEFAULT_FROM_EMAIL` and `SERVER_EMAIL` configuration options can be used to define the `From:` header of mails sent for internal authentication and error reporting (respectively).

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

    /etc/webapps/postorius/settings_local.py

    ALLOWED_HOSTS = [
        'localhost',
        'lists.example.com'
    ]

## Hosting

This article or section needs expansion.

Reason: Example for a setup using Apache HTTP Server. (Discuss in Talk:Postorius)
Note: Postorius needs to be run as its own user and group (i.e. `postorius`). It is using `/etc/webapps/postorius/`, `/var/lib/postorius/` and `/run/postorius/` for configurations, static caches and (potentially) sockets, respectively.
Note: As the static files are by default served from a top-level `static/` directory, which will conflict with hyperkitty on the same (sub)domain, it is advisable to set the `STATIC_URL` variable in `/etc/webapps/postorius/settings_local.py` to something unique (e.g. `'/postorius_static/'`).

### Nginx and uWSGI

Postorius comes with a working uWSGI configuration file in `/etc/uwsgi/postorius.ini`.

Install nginx and uwsgi-plugin-python, create a per-application socket for uWSGI (see UWSGI#Accessibility of uWSGI socket for reference) and enable `uwsgi-secure@postorius.socket`.

For a local test setup, serving Postorius at http://127.0.0.1:80/postorius add the following Nginx configuration to your setup:

    /etc/nginx/postorius.conf

    server {
      listen 80;
      server_name localhost;
      charset utf-8;
      client_max_body_size 75M;
      root /usr/share/webapps/postorius;
      access_log /var/log/nginx/access.postorius.log;
      error_log /var/log/nginx/error.postorius.log;

      location /postorius_static {
        alias /var/lib/postorius/static;
      }

      location ~^/(accounts|admin|postorius)/(.*)$ {
        include /etc/nginx/uwsgi_params;
        uwsgi_pass unix:/run/postorius/postorius.sock;
      }
    }

## Setup

Note: Run the following commands as the `postorius` user (e.g. using sudo or su).

After first installation make sure to generate a database:

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

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

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

Create a superuser account for the Django application:

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

## Tips and tricks

### Set an Alias Domain

To use a domain in a virtual alias domain setup with with postfix it is necessary to set the domain's `Alias Domain`. The domain name does not have to exist.

To set the `Alias Domain`, log in using the admin user (i.e. `postorius` by default) and alter the domain's settings it in the `Domains` menu.

## See also

- Postorius Documentation - The upstream documentation
- Mailman Suite Documentation - The (high level) upstream documentation for the entire Mailman Suite (Mailman, Hyperkitty and Postorius)

Categories:

- Mail server
- Web applications

Hidden category:

- Pages or sections flagged with Template:Expansion