Fix #187: documentation and changelog for email configuration

api/config/settings/common.py

@@ -172,7 +172,10 @@ FIXTURE_DIRS = (
 
 # EMAIL CONFIGURATION
 # ------------------------------------------------------------------------------
-EMAIL_BACKEND = env('DJANGO_EMAIL_BACKEND', default='django.core.mail.backends.smtp.EmailBackend')
+EMAIL_CONFIG = env.email_url(
+    'EMAIL_CONFIG', default='consolemail://')
+
+vars().update(EMAIL_CONFIG)
 
 # DATABASE CONFIGURATION
 # ------------------------------------------------------------------------------
@@ -367,6 +370,7 @@ CORS_ORIGIN_ALLOW_ALL = True
 #     'funkwhale.localhost',
 # )
 CORS_ALLOW_CREDENTIALS = True
+
 REST_FRAMEWORK = {
     'DEFAULT_PERMISSION_CLASSES': (
         'rest_framework.permissions.IsAuthenticated',

api/config/settings/local.py

@@ -25,9 +25,6 @@ SECRET_KEY = env("DJANGO_SECRET_KEY", default='mc$&b=5j#6^bv7tld1gyjp2&+^-qrdy=0
 # ------------------------------------------------------------------------------
 EMAIL_HOST = 'localhost'
 EMAIL_PORT = 1025
-EMAIL_BACKEND = env('DJANGO_EMAIL_BACKEND',
-                    default='django.core.mail.backends.console.EmailBackend')
-
 
 # django-debug-toolbar
 # ------------------------------------------------------------------------------

api/setup.cfg

@@ -11,7 +11,7 @@ python_files = tests.py test_*.py *_tests.py
 testpaths = tests
 env =
     SECRET_KEY=test
-    DJANGO_EMAIL_BACKEND=django.core.mail.backends.console.EmailBackend
+    EMAIL_CONFIG=consolemail://
     CELERY_BROKER_URL=memory://
     CELERY_TASK_ALWAYS_EAGER=True
     CACHEOPS_ENABLED=False

changes/changelog.d/187.feature

+Users can now request password reset by email, assuming
+a SMTP server was correctly configured (#187)
+
+Update
+^^^^^^
+
+Starting from this release, Funkwhale will send two types
+of emails:
+
+- Email confirmation emails, to ensure a user's email is valid
+- Password reset emails, enabling user to reset their password without an admin's intervention
+
+Email sending is disabled by default, as it requires additional configuration.
+In this mode, emails are simply outputed on stdout.
+
+If you want to actually send those emails to your users, you should edit your
+.env file and tweak the EMAIL_CONFIG variable. See :ref:`setting-EMAIL_CONFIG`
+for more details.
+
+.. note::
+
+  As a result of these changes, the DJANGO_EMAIL_BACKEND variable,
+  which was not documented, has no effect anymore. You can safely remove it from
+  your .env file if it is set.

deploy/env.prod.sample

@@ -6,6 +6,7 @@
 # - DJANGO_SECRET_KEY
 # - DJANGO_ALLOWED_HOSTS
 # - FUNKWHALE_URL
+# - EMAIL_CONFIG (if you plan to send emails)
 # On non-docker setup **only**, you'll also have to tweak/uncomment those variables:
 # - DATABASE_URL
 # - CACHE_URL
@@ -41,6 +42,16 @@ FUNKWHALE_API_PORT=5000
 # your instance
 FUNKWHALE_URL=https://yourdomain.funwhale
 
+# Configure email sending using this variale
+# By default, funkwhale will output emails sent to stdout
+# here are a few examples for this setting
+# EMAIL_CONFIG=consolemail://         # output emails to console (the default)
+# EMAIL_CONFIG=dummymail://          # disable email sending completely
+# On a production instance, you'll usually want to use an external SMTP server:
+# EMAIL_CONFIG=smtp://user@:password@youremail.host:25'
+# EMAIL_CONFIG=smtp+ssl://user@:password@youremail.host:465'
+# EMAIL_CONFIG=smtp+tls://user@:password@youremail.host:587'
+
 # Depending on the reverse proxy used in front of your funkwhale instance,
 # the API will use different kind of headers to serve audio files
 # Allowed values: nginx, apache2

docs/configuration.rst

@@ -39,6 +39,24 @@ settings in this interface.
 Configuration reference
 -----------------------
 
+.. _setting-EMAIL_CONFIG:
+
+``EMAIL_CONFIG``
+^^^^^^^^^^^^^^^^
+
+Determine how emails are sent.
+
+Default: ``consolemail://``
+
+Possible values:
+
+- ``consolemail://``: Output sent emails to stdout
+- ``dummymail://``: Completely discard sent emails
+- ``smtp://user:password@youremail.host:25``: Send emails via SMTP via youremail.host on port 25, without encryption, authenticating as user "user" with password "password"
+- ``smtp+ssl://user:password@youremail.host:465``: Send emails via SMTP via youremail.host on port 465, using SSL encryption, authenticating as user "user" with password "password"
+- ``smtp+tls://user:password@youremail.host:587``: Send emails via SMTP via youremail.host on port 587, using TLS encryption, authenticating as user "user" with password "password"
+
+
 .. _setting-MUSIC_DIRECTORY_PATH:
 
 ``MUSIC_DIRECTORY_PATH``