Skip to content

Commit 66e099f

Browse files
sdarwinsdarwin
committed
Add postgres and more documentation
1 parent 29bcd5a commit 66e099f

15 files changed

+563
-131
lines changed

‎README.md

+165-35
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,23 @@
11
Mailman 3 Ansible Role
22
======================
33

4-
See [docs/README.md](docs/README.md) for the C++ specific admin info.
5-
6-
`galaxyproject.mailman3` is an Ansible role to install the [Mailman 3][mailman3] suite. This role installs all
7-
components of the suite: Mailman 3 Core, and the Django-based web interfaces, Postorius and Hyperkitty.
4+
`cppalliance.mailman3` is an Ansible role to install the [Mailman 3][mailman3] suite, based on [galaxyproject.mailman3](https://github.com/galaxyproject/ansible-mailman3).
5+
While `galaxyproject.mailman3` installed all components of the suite: Mailman 3 Core, and the Django-based web interfaces, Postorius and Hyperkitty, this current role
6+
also adds basic installations of PostgreSQL, Postfix, and Nginx. Those 3rd party components are required by mailman3. However the option remains to install and
7+
manage those separately if you prefer.
88

99
Mailman 3 is a complicated service with many parts. It is a good idea to familiarize yourself with them before
1010
proceeding. See the [architecture documentation][mailman3_arch] for details.
1111

12+
See [docs/mailman3-core.md](docs/mailman3-core.md) for a version of this role that only installs mailman3-core and _not_ the web component.
13+
1214
[mailman3]: https://docs.mailman3.org/
1315
[mailman3_arch]: https://docs.mailman3.org/en/latest/architecture.html
1416

1517
Requirements
1618
------------
1719

18-
Any pre-requisites that may not be covered by Ansible itself or the role should be mentioned here. For instance, if the role uses the EC2 module, it may be a good idea to mention in this section that the boto package is required.
20+
Test has mainly been done on Ubuntu 22.04. Pull requests are welcome to verify and re-enable other OS versions.
1921

2022
Role Variables
2123
--------------
@@ -25,50 +27,177 @@ Variables are described in detail in [`defaults/main.yml`](defaults/main.yml).
2527
Dependencies
2628
------------
2729

28-
There are no strict depdendencies, but production Mailman 3 services typically need Postfix and PostgreSQL. You may find
29-
the following roles useful:
30+
A production Mailman 3 service typically needs Postfix, PostgreSQL, and Nginx. If you choose to install them separately, the following roles may be useful:
3031

3132
- [galaxyproject.postgresql](https://galaxy.ansible.com/galaxyproject/postgresql)
3233
- [galaxyproject.postgresql_objects](https://galaxy.ansible.com/galaxyproject/postgresql_objects)
3334
- [galaxyproject.postfix](https://galaxy.ansible.com/galaxyproject/postfix)
3435
- [galaxyproject.opendkim](https://galaxy.ansible.com/galaxyproject/opendkim)
3536
- [galaxyproject.nginx](https://galaxy.ansible.com/galaxyproject/nginx)
3637

38+
A default installation of this role `cppalliance.mailman3` will include those packages, as discussed below.
39+
40+
PostgreSQL
41+
----------
42+
43+
The playbook `playbooks/mailman3-playbook.yml` includes a database-specific play and will call `postgres.yml` to install the database.
44+
45+
```
46+
---
47+
- hosts: mailman3-database
48+
tasks:
49+
- name: Install DB
50+
ansible.builtin.include_role:
51+
name: cppalliance.mailman3
52+
tasks_from: database/main.yml
53+
```
54+
55+
Decide which server will host the database. It might be the mailman instance or a backend DB server. Add that server to the inventory (the hosts file) in the `mailman3-database` group. Run the playbook.
56+
57+
Otherwise, to manage the DB externally, don't put any hosts to the `mailman3-database` group. Or modify the play. Follow your own method to install a database.
58+
59+
Postgres configuration variables (named mailman3_database_) can be found in `defaults/main.yml`.
60+
61+
Postfix
62+
-------
63+
64+
The factor determining whether Postfix will be installed is the `mailman3_mta` variable in defaults/main.yml. If you choose to set the value of `mailman3_mta` to anything other than `postfix` it will avoid a Postfix installation.
65+
66+
Postfix related variables include `mailman3_relayhost` and `mailman3_sasl_passwd`. You _should_ configure those, but you may also choose to set each of those variables to an empty string `''` so they are not added in postfix/main.cf.
67+
68+
`postfix/main.cf` is a role template and may be customized or replaced.
69+
70+
Nginx
71+
-----
72+
73+
The factor determining whether Nginx will be installed is the `mailman3_install_nginx` variable in defaults/main.yml. If you choose to set the value to `false` it will avoid an Nginx installation.
74+
75+
This role doesn't install SSL certificates, but you should likely add them. Review the `mailman3_nginx_ssl_certs` variable which starts out using self-signed certificates. After you have installed valid certificates set that variable to use another configuration.
76+
3777
Example Playbook
3878
----------------
3979

40-
A relatively simple, single-site setup using PostgreSQL as the database backend:
80+
A playbook has been included in playbooks/mailman3-playbook.yml:
81+
82+
```
83+
---
84+
- hosts: mailman3-database
85+
become: true
86+
remote_user: ubuntu
87+
tasks:
88+
- name: Install DB
89+
ansible.builtin.include_role:
90+
name: cppalliance.mailman3
91+
tasks_from: database/main.yml
92+
93+
- hosts: mailman3
94+
become: true
95+
remote_user: ubuntu
96+
roles:
97+
- role: cppalliance.mailman3
98+
99+
```
100+
101+
In the inventory `hosts` file add servers to the `mailman3` and `mailman3-database` groups. Configure variables in a file such as host_vars/mailman.example.org/vars.
102+
The following example uses a network connection to reach the database:
41103

42104
```yaml
43-
- name: Install Mailman 3
44-
hosts: all
45-
vars:
46-
mailman3_django_superusers:
47-
- name: admin
48-
pass: admin
49-
email: [email protected]
50-
mailman3_core_api_admin_user: adminuser
51-
mailman3_core_api_admin_pass: adminpass
52-
mailman3_archiver_key: archiverkey
53-
mailman3_config:
54-
mailman:
55-
site_owner: [email protected]
56-
database:
57-
class: mailman.database.postgresql.PostgreSQLDatabase
58-
url: postgres:///mailman3_core?host=/var/run/postgresql
59-
mailman3_django_config:
60-
secret_key: supersecret
61-
hyperkitty_attachment_folder: "{{ mailman3_web_var_dir }}/attachments"
62-
databases:
63-
default:
64-
ENGINE: django.db.backends.postgresql_psycopg2
65-
NAME: mailman3_web
66-
HOST: /var/run/postgresql
67-
mailman3_extra_packages:
68-
- psycopg2-binary
105+
mailman3_django_superusers:
106+
- name: admin
107+
pass: admin
108+
email: [email protected]
109+
mailman3_core_api_admin_user: adminuser
110+
mailman3_core_api_admin_pass: adminpass
111+
mailman3_archiver_key: archiverkey
112+
mailman3_config:
113+
mailman:
114+
site_owner: [email protected]
115+
database:
116+
class: mailman.database.postgresql.PostgreSQLDatabase
117+
url: postgresql://mailman3_core:[email protected]/mailman3_core
118+
mailman3_django_config:
119+
secret_key: supersecret
120+
# Don't define hyperkitty_attachment_folder. If not set, it will store attachments in the db.
121+
# hyperkitty_attachment_folder: "{{ mailman3_web_var_dir }}/attachments"
122+
csrf_trusted_origins:
123+
- http://mailman.example.org
124+
- https://mailman.example.org
125+
databases:
126+
default:
127+
ENGINE: 'django.db.backends.postgresql_psycopg2'
128+
NAME: 'mailman3_web'
129+
HOST: 'mailman.example.org'
130+
USER: 'mailman3_web'
131+
PASSWORD: 'mypassword'
132+
PORT: '5432'
133+
mailman3_extra_packages:
134+
- psycopg2-binary
135+
mailman3_nginx_ssl_certs: |
136+
include snippets/snakeoil.conf;
137+
# ssl_certificate /etc/letsencrypt/live/{{ mailman3_web_url }}/fullchain.pem;
138+
# ssl_certificate_key /etc/letsencrypt/live/{{ mailman3_web_url }}/privkey.pem;
139+
mailman3_sasl_passwd: smtp.mailgun.org [email protected]:555555555
140+
mailman3_relayhost: smtp.mailgun.org:587
141+
mailman3_database_list:
142+
- name: mailman3_web
143+
username: mailman3_web
144+
password: mypassword
145+
subnet: "0.0.0.0/0"
146+
- name: mailman3_core
147+
username: mailman3_core
148+
password: mypassword
149+
subnet: "0.0.0.0/0"
150+
```
151+
152+
Similarly, an example with a unix socket to reach the database. Notice the database username change:
153+
154+
```yaml
155+
mailman3_django_superusers:
156+
- name: admin
157+
pass: admin
158+
email: [email protected]
159+
mailman3_core_api_admin_user: adminuser
160+
mailman3_core_api_admin_pass: adminpass
161+
mailman3_archiver_key: archiverkey
162+
mailman3_config:
163+
mailman:
164+
site_owner: [email protected]
165+
database:
166+
class: mailman.database.postgresql.PostgreSQLDatabase
167+
url: postgres:///mailman3_core?host=/var/run/postgresql
168+
mailman3_django_config:
169+
secret_key: supersecret
170+
# Don't define hyperkitty_attachment_folder. If not set, it will store attachments in the db.
171+
# hyperkitty_attachment_folder: "{{ mailman3_web_var_dir }}/attachments"
172+
csrf_trusted_origins:
173+
- http://mailman.example.org
174+
- https://mailman.example.org
175+
databases:
176+
default:
177+
ENGINE: django.db.backends.postgresql_psycopg2
178+
NAME: mailman3_web
179+
HOST: /var/run/postgresql
180+
mailman3_extra_packages:
181+
- psycopg2-binary
182+
mailman3_nginx_ssl_certs: |
183+
include snippets/snakeoil.conf;
184+
# ssl_certificate /etc/letsencrypt/live/{{ mailman3_web_url }}/fullchain.pem;
185+
# ssl_certificate_key /etc/letsencrypt/live/{{ mailman3_web_url }}/privkey.pem;
186+
mailman3_sasl_passwd: smtp.mailgun.org [email protected]:555555555
187+
mailman3_relayhost: smtp.mailgun.org:587
188+
mailman3_database_list:
189+
- name: mailman3_web
190+
# With a unix socket the db username should match the linux username, which is often "mailman3-web".
191+
username: mailman3-web
192+
password: mypassword
193+
subnet: "0.0.0.0/0"
194+
- name: mailman3_core
195+
username: mailman3_core
196+
password: mypassword
197+
subnet: "0.0.0.0/0"
69198
```
70199
71-
A more complex setup with multiple list domains, Xapian haystack engine, distribution of Postfix lmtp maps to MX
200+
The next example comes from the original galaxyproject role. A more complex setup with multiple list domains, Xapian haystack engine, distribution of Postfix lmtp maps to MX
72201
servers, and DKIM:
73202
74203
```yaml
@@ -137,4 +266,5 @@ MIT
137266
Author Information
138267
------------------
139268
269+
The [CPPAlliance](https://cppalliance.org)
140270
The [Galaxy Community](https://galaxyproject.org/) and [contributors](https://github.com/galaxyproject/ansible-mailman3/graphs/contributors)

‎defaults/main.yml

+21-2
Original file line numberDiff line numberDiff line change
@@ -431,9 +431,28 @@ __mailman3_os: >-
431431
# Server name nginx should listen on, defaults to inventory_hostname.
432432
mailman3_web_url: "{{ inventory_hostname }}"
433433
mailman3_install_nginx: true
434-
# Override this will a value similar to mailman3_web_url. Used in /etc/mailman3/hyperkitty.cfg:
435-
mailman3_hyperkitty_server_url: "http://localhost"
434+
# Similar to mailman3_web_url. Used in /etc/mailman3/hyperkitty.cfg:
435+
mailman3_hyperkitty_server_url: "https://{{ inventory_hostname }}"
436436
mailman3_nginx_ssl_certs: "include snippets/snakeoil.conf;"
437437
mailman3_mta: postfix
438438
mailman3_relayhost: smtp.mailgun.org:587
439439
mailman3_sasl_passwd: smtp.mailgun.org [email protected]:12345
440+
441+
# Database variables
442+
mailman3_database_type: postgres
443+
mailman3_database_pg_packages:
444+
- postgresql-15
445+
# - postgresql-contrib
446+
- libpq-dev
447+
- python3-pip
448+
mailman3_database_super_password: superpassword
449+
mailman3_postgresql_config_dir: "/etc/postgresql/15"
450+
mailman3_database_list:
451+
- name: mailman3_web
452+
username: mailman3_web
453+
password: mypassword
454+
subnet: "0.0.0.0/0"
455+
- name: mailman3_core
456+
username: mailman3_core
457+
password: mypassword
458+
subnet: "0.0.0.0/0"

‎docs/README.md

-69
This file was deleted.

‎docs/cron.d.example1

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# /etc/cron.d/mailman-web
2+
#Ansible: hourly
3+
@hourly mailman3-web MAILMAN_WEB_CONFIG=/var/lib/mailman3/web/project/settings.py /opt/mailman3/bin/mailman-web runjobs hourly
4+
#Ansible: daily
5+
@daily mailman3-web MAILMAN_WEB_CONFIG=/var/lib/mailman3/web/project/settings.py /opt/mailman3/bin/mailman-web runjobs daily
6+
#Ansible: weekly
7+
@weekly mailman3-web MAILMAN_WEB_CONFIG=/var/lib/mailman3/web/project/settings.py /opt/mailman3/bin/mailman-web runjobs weekly
8+
#Ansible: monthly
9+
@monthly mailman3-web MAILMAN_WEB_CONFIG=/var/lib/mailman3/web/project/settings.py /opt/mailman3/bin/mailman-web runjobs monthly
10+
#Ansible: yearly
11+
@yearly mailman3-web MAILMAN_WEB_CONFIG=/var/lib/mailman3/web/project/settings.py /opt/mailman3/bin/mailman-web runjobs yearly
12+
#Ansible: minutely
13+
* * * * * mailman3-web MAILMAN_WEB_CONFIG=/var/lib/mailman3/web/project/settings.py /opt/mailman3/bin/mailman-web runjobs minutely
14+
#Ansible: quarter_hourly
15+
2,17,32,47 * * * * mailman3-web MAILMAN_WEB_CONFIG=/var/lib/mailman3/web/project/settings.py /opt/mailman3/bin/mailman-web runjobs quarter_hourly

0 commit comments

Comments
 (0)