SMTP Email Setup for Discourse Docker Guide

This guide walks you through configuring SMTP email for a self-hosted Discourse forum running in Docker. You’ll edit the app.yml file, rebuild the container, and verify that emails send correctly. You’ll need root or sudo access to your server and the SMTP credentials from your email provider.

What You’ll Need

• A server running Discourse via Docker (installed using the official discourse-setup script or manually).
• SMTP server hostname, port, username, and password (e.g., from your email host, transactional email service, or your own mail server).
• Access to the Discourse installation directory (usually /var/discourse).
• Ability to edit files with a text editor (e.g., nano or vim).
• A domain name that is properly configured for your Discourse instance (for DKIM/SPF if applicable).

Step-by-Step

1. SSH into your server and navigate to the Discourse installation directory: cd /var/discourse.
2. Open the app.yml file for editing: sudo nano containers/app.yml. This file contains all the Docker configuration for your Discourse instance.
3. Find the SMTP section in the file. It looks like this (with placeholder values):

   ## SMTP settings
   smtp_address: smtp.example.com
   smtp_port: 587
   smtp_user_name: yourusername
   smtp_password: yourpassword
   smtp_authentication: plain
   smtp_enable_starttls_auto: true
   smtp_openssl_verify_mode: none
   

   If the section doesn’t exist, add it under the env: block. The env: block is where all environment variables for the container are defined.

4. Replace the placeholder values with your actual SMTP details:
   • smtp_address: Your SMTP server hostname (e.g., smtp.gmail.com for Gmail, smtp.mailgun.org for Mailgun).
   • smtp_port: Usually 587 for TLS/STARTTLS, 465 for SSL, or 25 for plain (not recommended). Check with your provider.
   • smtp_user_name: Your SMTP username (often the full email address).
   • smtp_password: Your SMTP password or API key.
   • smtp_authentication: Usually plain or login.
   • smtp_enable_starttls_auto: Set to true if your provider supports STARTTLS (most do).
   • smtp_openssl_verify_mode: Leave as none unless you have a valid certificate chain issue; for production, consider setting to peer but be aware of potential issues.
5. Add the ‘From’ address (optional but recommended). In the same env: block, add:

   DISCOURSE_SMTP_FROM_ADDRESS: 'noreply@yourdomain.com'

   This is the address that emails will appear to come from. It should be a real address that can receive replies if you want replies to work.

6. Save the file and exit the editor.
7. Rebuild the Discourse container to apply the changes. Run: sudo ./launcher rebuild app. This will take a few minutes. It stops the container, applies the new configuration, and restarts it.
8. Verify the rebuild completed successfully. You should see no errors. If there are errors, check the logs with sudo ./launcher logs app.
9. Test email sending from the Discourse admin panel. Go to https://yourforum.com/admin/email and click the “Send test email” button. Enter your email address and click send.
10. Check the email log if the test fails. In the same admin page, you can view the email logs to see any error messages returned by the SMTP server.

Common Mistakes

• Using the wrong port: Many providers block port 25. Use 587 or 465 as recommended.
• Forgetting to rebuild: Editing app.yml alone does nothing. You must rebuild the container.
• Incorrect SMTP username: Some providers expect the full email address, others just the part before the @. Check your provider’s docs.
• Not enabling STARTTLS: If your provider requires it and you leave it off, emails will fail.
• Using a ‘From’ address that is not allowed: Some providers only allow sending from addresses you’ve verified. Use an address that matches your SMTP account.
• Copy-pasting spaces: Ensure there are no trailing spaces in the YAML values, as YAML is sensitive to indentation and whitespace.

Tips

• Use a dedicated transactional email service (like Mailgun, SendGrid, or Amazon SES) for better deliverability and to avoid being marked as spam.
• Set up SPF, DKIM, and DMARC records for your sending domain to improve email deliverability. Your SMTP provider will give you the exact records to add to your DNS.
• If you use Gmail or Google Workspace, you may need to generate an “App Password” if you have 2-factor authentication enabled.
• Test with a real email account you control, not just a fake address.
• Keep your SMTP password in a secure place; consider using environment variables or a secrets manager if you’re comfortable with that.

Troubleshooting

If emails are not sending, follow these steps:

1. Check the email logs in the admin panel. Look for error messages like “connection refused”, “authentication failed”, or “timeout”.
2. Test the SMTP connection manually from your server using telnet or openssl s_client to see if the port is open and the server responds.
3. Verify your SMTP credentials by logging into your email provider’s web interface or using a tool like swaks to send a test email directly.
4. Check the Discourse logs for any errors during the rebuild: sudo ./launcher logs app and look for lines containing “smtp” or “mail”.
5. If you’re using a firewall, ensure that outbound connections to the SMTP port are allowed. Some cloud providers block port 25 by default.
6. If you’re using a proxy or VPN, it might interfere with SMTP connections. Try disabling it temporarily.
7. If all else fails, temporarily set smtp_openssl_verify_mode: none and smtp_enable_starttls_auto: false to see if it’s a TLS issue. If it works, then the problem is with certificate verification.

Frequently Asked Questions

1. Do I need to rebuild the container every time I change SMTP settings? Yes, any changes to app.yml require a rebuild (sudo ./launcher rebuild app) to take effect.
2. Can I use the same SMTP server for multiple Discourse forums? Yes, as long as your SMTP provider allows it and you have separate credentials or use a catch-all address. Be aware of sending limits.
3. What is the difference between port 587 and 465? Port 587 is for STARTTLS (the connection starts plain and then upgrades to TLS). Port 465 is for implicit SSL (the connection is TLS from the start). Use the one your provider specifies.
4. Why are my emails going to spam? This is often due to missing SPF/DKIM records or a low sender reputation. Set up the DNS records and consider using a dedicated sending service.
5. Can I use a Gmail account to send emails? Yes, but you’ll need to enable “Less secure app access” or use an App Password, and you’ll hit sending limits (500 per day for free accounts). It’s not recommended for production.
6. How do I change the email subject prefix? That’s a separate setting in the Discourse admin panel under Settings > Basic Setup > “Email subject prefix”. It doesn’t require a rebuild.

Related

• Data Center Power Demand Growth & Limits
• Oracle Gas Truck Data Center Power Delays?
• Cloud Storage Buying Factors: What to Consider