Merge pull request #1080 from Supermathie/sysadmin-docs
Add documentation for discourse email setup
This commit is contained in:
Jeff Atwood
commit
686d1c0c25
|
|
@ -0,0 +1,157 @@
|
|||
# Discourse Mail Setup Guide
|
||||
|
||||
After following INSTALL-ubuntu.md your mailer settings should still be set (in
|
||||
`config/environments/production.rb`, remember) to:
|
||||
|
||||
```ruby
|
||||
config.action_mailer.delivery_method = :sendmail
|
||||
config.action_mailer.sendmail_settings = {arguments: '-i}
|
||||
```
|
||||
|
||||
That's great. Leave that there as we're going to try to get the mail to postfix
|
||||
ASAP so postfix do it's job and process the mail for delivery.
|
||||
|
||||
## Email is IMPORTANT
|
||||
|
||||
Email notifications are core to the Discourse experience. We want your users to receive notifications as soon as possible so they can contribute to the conversation.
|
||||
|
||||
If sending email isn't something to which you want to devote your time, don't
|
||||
worry about it. There are [companies](http://mandrill.com/) that dedicate
|
||||
theirs to doing one thing very well - ensuring that mail to your users gets
|
||||
delivered.
|
||||
|
||||
## Sending Email Through GMail
|
||||
|
||||
Don't do it! GMail is not intended for sending out bulk notifications. Your email setup [will break](http://webapps.stackexchange.com/q/44768/12456).
|
||||
|
||||
## Sending Email Through Mandrill
|
||||
|
||||
### Create an account
|
||||
We're going to use [Mandrill](http://mandrill.com/) as our email delivery
|
||||
provider.
|
||||
|
||||
|
||||
|
||||
1. Create an account at http://mandrill.com/ (click on 'SIGN UP')
|
||||
|
||||
1. I filled out the 'Tell Us A Little About Yourself' survey. They are
|
||||
providing us a free service, after all!
|
||||
|
||||
### Create an API key
|
||||
I'm pleased with Mandrill's setup - this is the Right Way to do things.
|
||||
|
||||
|
||||
1. Click 'Get SMTP Credentials'
|
||||
|
||||
|
||||
1. Note that you can use 'any valid API key' as your password. Click '+ Add API Key' to create one.
|
||||
|
||||
|
||||
|
||||
1. Click 'Edit' to document for what we'll be using this key.
|
||||
|
||||
|
||||
1. Since we'll only be using this key for sending email and *nothing else*, check 'Only Allow This Key To Use Certain API Calls' and select only Messages / Send
|
||||
|
||||
|
||||
1. Optionally, restrict this key to the public static IP address of your server.
|
||||
|
||||
1. Click 'Save'
|
||||
|
||||
### Configure Postfix for Mandrill
|
||||
|
||||
Thank you Mandrill for providing an excellent [guide on configuring Postfix to use Mandrill](http://help.mandrill.com/entries/23060367-Can-I-configure-Postfix-to-send-through-Mandrill-).
|
||||
|
||||
Additional notes on this document:
|
||||
|
||||
* Ubuntu has an `/etc/postfix/sasl` directory. Create a password file in there.
|
||||
|
||||
* Make sure you put your **API KEY** into this password file, not your **ACCOUNT PASSWORD**
|
||||
|
||||
* You may already have configured a `relayhost` earlier in the installation. If this machine is sending out ANY emails other than Discourse-generated notifications, follow the instructions in 'Relay only certain emails through Mandrill'.
|
||||
|
||||
After configuring postfix as per Mandrill's instructions, reload postfix with `sudo postfix reload`.
|
||||
|
||||
### Send test email
|
||||
|
||||
|
||||
Now we send a test email. Login to your Discourse installation and click on the ≡ (aka congruence/hamburger/etc), then 'Admin'.
|
||||
|
||||
|
||||
Click on `Email`, `Settings`, then type your email address into the test box and click `send test email`.
|
||||
|
||||
Within moments, you should have email in your Inbox.
|
||||
|
||||
### OH NOES I DIDN'T GET MY EMAIL TEST!
|
||||
|
||||
Follow the trail. First of all, did the email get to Postfix? Check `/var/log/mail.log`:
|
||||
|
||||
Jun 24 01:24:59 discoursetest postfix/pickup[25387]: 7CBF280294C: uid=1001 from=<info@discourse.org>
|
||||
Jun 24 01:24:59 discoursetest postfix/cleanup[25829]: 7CBF280294C: message-id=<51c7d82b6f878_8ef3d7802c10139@discoursetest.mail>
|
||||
Jun 24 01:24:59 discoursetest postfix/qmgr[25386]: 7CBF280294C: from=<info@discourse.org>, size=5884, nrcpt=1 (queue active)
|
||||
|
||||
Looks good! Wait, why is the email coming *from* `info@discourse.org`? That's a
|
||||
problem we'll fix below.
|
||||
|
||||
Jun 24 01:25:04 discoursetest postfix/smtp[25831]: 7CBF280294C: SASL authentication failed; server smtp.mandrillapp.com[54.235.146.179] said: 435 4.7.8 Error: authentication failed:
|
||||
Jun 24 01:25:10 discoursetest postfix/smtp[25831]: 7CBF280294C: SASL authentication failed; server smtp.mandrillapp.com[54.234.14.176] said: 435 4.7.8 Error: authentication failed:
|
||||
Jun 24 01:25:13 discoursetest postfix/smtp[25831]: 7CBF280294C: SASL authentication failed; server smtp.mandrillapp.com[50.16.10.62] said: 435 4.7.8 Error: authentication failed:
|
||||
Jun 24 01:25:20 discoursetest postfix/smtp[25831]: 7CBF280294C: to=<spoonman@discourse.org>, relay=smtp.mandrillapp.com[54.235.146.152]:25, delay=21, delays=0.07/0.01/21/0, dsn=4.7.8, status=deferred (SASL authentication failed; server smtp.mandrillapp.com[54.235.146.152] said: 435 4.7.8 Error: authentication failed: )
|
||||
|
||||
The above errors are caused by using an incorrect API key in your sasl passwords file. Fix that (edit `/etc/postfix/sasl/passwd`, run `sudo postmap` on it, then `postqueue -f` to restart the queue).
|
||||
|
||||
Jun 24 01:30:30 discoursetest postfix/smtp[25861]: table hash:/etc/postfix/sasl/passwd(0,lock|fold_fix) has changed -- restarting
|
||||
Jun 24 01:30:31 discoursetest postfix/smtp[25872]: 7CBF280294C: to=<spoonman@discourse.org>, relay=smtp.mandrillapp.com[54.234.14.176]:25, delay=332, delays=331/0.01/1.2/0.17, dsn=2.0.0, status=sent (250 2.0.0 Ok: queued as C515B6380D3)
|
||||
|
||||
That's better! Our test message made it to Mandrill. Let's check Outbound Activity in Mandrill:
|
||||
|
||||
|
||||
|
||||
|
||||
If you see this, the email was accepted by Mandrill and delivered to the
|
||||
destination. You need to check your spam filter now.
|
||||
|
||||
If you don't see anything in Mandrill, ensure that the API key is enabled for
|
||||
'Send-Raw' permission. Mandrill appears to silently drop the email if that's
|
||||
not set.
|
||||
|
||||
### Configure notification email addresses
|
||||
|
||||
Login to Discourse, go to the Admin page and select 'Settings'.
|
||||
|
||||
Filter with the string 'system'.
|
||||
|
||||
* Ensure that `system_username` is set to an email address for an appropriate "owner" of the forum
|
||||
* Set `notification_email` to 'noreply@', 'nobody@' as appropriate.
|
||||
|
||||
Filter with the string 'contact_email'
|
||||
|
||||
* Ensure `contact_email` is set appropriately.
|
||||
|
||||
### SPF and DKIM records
|
||||
|
||||
Login to Mandrill and click on ⚙ (Settings)-> Sending Domains
|
||||
|
||||
If your domain isn't listed, add it. It'll probably show this:
|
||||
|
||||
|
||||
|
||||
Click 'View DKIM/SPF setup instructions'.
|
||||
|
||||
Follow the instructions there.
|
||||
|
||||
When DNS is properly configured, you should be able to click on 'Test DNS Settings' and Mandrill will confirm they are setup properly:
|
||||
|
||||
|
||||
|
||||
### Mandrill Options
|
||||
|
||||
Login to Mandrill and click on ⚙ (Settings)-> Sending Options
|
||||
|
||||
* 'Track Clicks' is enabled by default. This rewrites links in email messages to bounce off the mandrillapp.com domain for click tracking. Disable it here if you don't want that:
|
||||
|
||||
|
||||
|
||||
* If you do use it, setting up a 'Tracking Domain' is a very good idea to avoid erroneous scam warnings:
|
||||
|
||||
|
||||
|
|
@ -325,6 +325,20 @@ and create an account by logging in normally, then run the commands:
|
|||
> me.admin = true
|
||||
> me.save
|
||||
|
||||
## Site localization
|
||||
|
||||
Custom assets such as images should be placed somewhere under:
|
||||
|
||||
DISCOURSE_HOME/public/
|
||||
|
||||
For example, create a `local` directory and place it into:
|
||||
|
||||
DISCOURSE_HOME/public/uploads/local/michael.png
|
||||
|
||||
The corresponding site setting is:
|
||||
|
||||
logo_small_url: /uploads/local/michael.png
|
||||
|
||||
## Updating Discourse
|
||||
|
||||
# Run these commands as the discourse user
|
||||
|
|
@ -340,3 +354,5 @@ and create an account by logging in normally, then run the commands:
|
|||
RUBY_GC_MALLOC_LIMIT=90000000 RAILS_ENV=production rake db:migrate
|
||||
RUBY_GC_MALLOC_LIMIT=90000000 RAILS_ENV=production rake assets:precompile
|
||||
bluepill start
|
||||
|
||||
Note that if bluepill *itself* needs to be restarted, it must be killed with `bluepill quit` and restarted with the same command that's in crontab
|
||||
|
|
|
|||
Loading…
Reference in New Issue