Adding reCAPTCHA v3 to Mailman3

1 · Overview

The pbiering/mailman3-rpm repository ships patch files that inject CAPTCHA support into Mailman3's web interface. The patches work by importing a small dispatcher module (django_multi_captcha_support.py) that routes to whichever CAPTCHA service is configured in settings.py.

Four locations are patched:

2 · Prerequisites

• Mailman3 installed in a Python virtualenv (this guide assumes /opt/mailman/venv/)
• Config files in /etc/mailman3/
• Root or sudo access to the server
• A Google reCAPTCHA v3 site key + secret key registered for your domain at google.com/recaptcha/admin
• Internet access from the server (to clone the patch repo and pip install)

3 · Step-by-Step Implementation

source /opt/mailman/venv/bin/activate
python -m pip show postorius django django-allauth

cd ~
git clone https://github.com/pbiering/mailman3-rpm.git
cd mailman3-rpm
ls *.patch   # verify patch files are present

pip install django-recaptcha django-hcaptcha django-friendly-captcha django-turnstile

cp ~/mailman3-rpm/django_multi_captcha_support.py \
   /opt/mailman/venv/lib/python3.11/site-packages/

VENV=/opt/mailman/venv/lib/python3.11/site-packages

patch --directory="$VENV" -p0 \
  < ~/mailman3-rpm/mailman3-postorius-forms-list_forms.py-CAPTCHA.patch

patch --directory="$VENV" -p0 --fuzz=4 \
  < ~/mailman3-rpm/mailman3-allauth-account-forms.py-CAPTCHA.patch

patching file allauth/account/forms.py
Hunk #1 succeeded at 35 (offset 4 lines).
Hunk #2 succeeded at 67 with fuzz 4 (offset -23 lines).
Hunk #3 succeeded at 276 with fuzz 2 (offset -12 lines).
Hunk #4 succeeded at 544 with fuzz 2 (offset -27 lines).

# Patch the Python authentication form
patch --directory="$VENV" -p0 \
  < ~/mailman3-rpm/mailman3-django-contrib-admin-forms.py-CAPTCHA.patch

# Patch the HTML login template
patch --directory="$VENV" -p0 \
  < ~/mailman3-rpm/mailman3-django-contrib-admin-templates-admin-login.html-CAPTCHA.patch

find /opt/mailman/venv -name "*.rej" 2>/dev/null

### CAPTCHA support
CAPTCHA_SERVICE = 'recaptchaV3'
RECAPTCHA_PUBLIC_KEY_V3  = 'your-site-key-here'
RECAPTCHA_PRIVATE_KEY_V3 = 'your-secret-key-here'
INSTALLED_APPS += ['django_recaptcha']

mailman-web collectstatic --noinput
systemctl restart mailman3 mailmanweb

systemctl status mailman3 mailmanweb
journalctl -u mailmanweb -n 20

4 · Verification

After restarting, confirm the integration is working:

4.1 Check INSTALLED_APPS

source /opt/mailman/venv/bin/activate
python -c "
import django, os
os.environ.setdefault('DJANGO_SETTINGS_MODULE','mailman_web.settings')
django.setup()
from django.conf import settings
print('django_recaptcha in INSTALLED_APPS:', 'django_recaptcha' in settings.INSTALLED_APPS)
print('CAPTCHA_SERVICE:', settings.CAPTCHA_SERVICE)
"

4.2 Visual check

Visit the following pages on your site and look for the reCAPTCHA badge (bottom-right corner):

• Anonymous subscribe form: https://lists.yourdomain/mm/lists/<listname>/
• User login: https://lists.yourdomain/accounts/login/
• Django admin: https://lists.yourdomain/admin/login/

5 · Important Maintenance Notes

Re-apply script

Save the following as /opt/mailman/apply-captcha-patches.sh and run it after any package upgrade:

#!/bin/bash
# Re-apply CAPTCHA patches after pip upgrades
set -e
VENV=/opt/mailman/venv/lib/python3.11/site-packages
PATCHES=~/mailman3-rpm

source /opt/mailman/venv/bin/activate

cp "$PATCHES/django_multi_captcha_support.py" "$VENV/"

patch --directory="$VENV" -p0 \
  < "$PATCHES/mailman3-postorius-forms-list_forms.py-CAPTCHA.patch"

patch --directory="$VENV" -p0 --fuzz=4 \
  < "$PATCHES/mailman3-allauth-account-forms.py-CAPTCHA.patch"

patch --directory="$VENV" -p0 \
  < "$PATCHES/mailman3-django-contrib-admin-forms.py-CAPTCHA.patch"

patch --directory="$VENV" -p0 \
  < "$PATCHES/mailman3-django-contrib-admin-templates-admin-login.html-CAPTCHA.patch"

mailman-web collectstatic --noinput
systemctl restart mailmanweb

echo "Done."

6 · Completion Checklist

• Patch repo cloned to ~/mailman3-rpm/
• CAPTCHA Python libraries installed in venv
• django_multi_captcha_support.py copied to site-packages
• Postorius patch applied (list subscription form)
• django-allauth patch applied (login / signup / password-reset)
• Django admin form patch applied
• Django admin template patch applied
• No .rej files found
• CAPTCHA_SERVICE and keys set in /etc/mailman3/settings.py
• django_recaptcha (or chosen service) in INSTALLED_APPS
• Static files collected
• Services restarted and running cleanly
• reCAPTCHA badge visible on subscribe / login pages
• Re-apply script saved for post-upgrade use

Appendix A — Lazy-import variant of django_multi_captcha_support.py

The original django_multi_captcha_support.py imports all four captcha libraries at module load time. If only one library is installed, Django will refuse to start with a ModuleNotFoundError. The patched version below uses lazy imports — only the configured service's library is imported at runtime:

#### Multi CAPTCHA Support for Django — lazy-import variant
# Only imports the library for the configured CAPTCHA_SERVICE.
from django.conf import settings

def multicaptcha(action):
    captcha_service = getattr(settings, 'CAPTCHA_SERVICE', None)
    if captcha_service is not None:
        if captcha_service in ('recaptcha', 'recaptchaV2C'):
            from django_recaptcha.fields import ReCaptchaField
            from django_recaptcha.widgets import ReCaptchaV2Checkbox
            pub = getattr(settings, 'RECAPTCHA_PUBLIC_KEY_V2C', None)
            prv = getattr(settings, 'RECAPTCHA_PRIVATE_KEY_V2C', None)
            return ReCaptchaField(widget=ReCaptchaV2Checkbox,
                **({'public_key': pub, 'private_key': prv} if pub else {}))
        elif captcha_service == 'recaptchaV2I':
            from django_recaptcha.fields import ReCaptchaField
            from django_recaptcha.widgets import ReCaptchaV2Invisible
            pub = getattr(settings, 'RECAPTCHA_PUBLIC_KEY_V2I', None)
            prv = getattr(settings, 'RECAPTCHA_PRIVATE_KEY_V2I', None)
            return ReCaptchaField(widget=ReCaptchaV2Invisible,
                **({'public_key': pub, 'private_key': prv} if pub else {}))
        elif captcha_service == 'recaptchaV3':
            from django_recaptcha.fields import ReCaptchaField
            from django_recaptcha.widgets import ReCaptchaV3
            pub = getattr(settings, 'RECAPTCHA_PUBLIC_KEY_V3', None)
            prv = getattr(settings, 'RECAPTCHA_PRIVATE_KEY_V3', None)
            return ReCaptchaField(widget=ReCaptchaV3(action=action),
                **({'public_key': pub, 'private_key': prv} if pub else {}))
        elif captcha_service == 'hcaptcha':
            from hcaptcha.fields import hCaptchaField
            return hCaptchaField()
        elif captcha_service == 'friendlycaptcha':
            from friendly_captcha.fields import FrcCaptchaField
            return FrcCaptchaField()
        elif captcha_service == 'turnstile':
            from turnstile.fields import TurnstileField
            return TurnstileField()
    return None

Appendix B — Troubleshooting