Switch default mail transport to Swift_SendmailTransport
Closed this issue · 10 comments
For backwards compatibility, we've re added the deprecated and removed class Swift_MailTransport back into our own code base silverstripe/silverstripe-framework#10048. This was so that existing sites don't silently break email on upgrade
For new projects, consider adding config to installer to set the default mail transport class to Swift_SendmailTransport, which has additional security over the Swift_MailTransport class - see swiftmailer/swiftmailer#866 for a discussion around why Swift_MailTransport was removed in the first place
The major downside with doing this is that some websites on some servers won't send emails out of the box i.e. a sendmail binary isn't installed/configured. All sites require email functionality so that 'Forgot password' functionality works. Silverstripe does not require an email to be sent for the site to be setup, so user may not know for several months that email does not work, until they need to use the forgot password functionality, potentially leading non-technical users to be locked out of their own site
We could potentially do this by having NO Transport class installed by default (by setting the Transport to null via the installer 'glue', and putting a warning inside the CMS saying that a developer needs to configure mail themselves, either Swift_SendmailTransport or Swift_SmtpTransport.
ACs
- For the installer recipe, switch default mail transport to Swift_SendmailTransport
- Clear documentation is added to getting started developer guide
- Provide a sample code snippet in dev docs for testing that email is working early on in the project
- Ensure platform documentation notes that this is supported (and how)
- Note that the old class is deprecated in the code
- Note that the old class is deprecated in the upcoming changelog, and add notes in any related documentation
- Update changelog saying installer change and encourage existing users to update
PRs
Waiting to hear back on internal discussion regarding platform docs https://silverstripeltd.slack.com/archives/GNHGJT5G8/p1629331104008900
https://servicedesk.silverstripe.cloud/support/solutions/articles/75000012863-emails
1/
double check that the first line
By default your environment is configured to send emails from the placeholder domain “no-reply@-.sites.silverstripe.com”; this is configured from the variables section of your environment with the SS_SEND_ALL_EMAILS_FROM environment variable.
Is also correct for SCPS - have asked internally - https://silverstripeltd.slack.com/archives/CEYE6K29Y/p1629847154025100
2/
Remove this section (it's being moved to dev docs)
Configure Silverstripe to use the sender domain for emails
First, configure your Silverstripe site’s default ‘from’ address for emails, such as password reset emails, by following the administrator emails documentation.
Then ensure that you send emails from your application with the correct from address:
$email = new Email('no-reply@example.com', 'user@gmail.com', 'hello', 'email body text');
For more extensive documentation on how to use the Silverstripe emailer, see the API documentation.
You will also have to remove the SS_SEND_ALL_EMAILS_FROM environment variable.
3/
Add remove it with the following following:
See the [developer documentation](https://docs.silverstripe.org/en/4/getting_started/#email) for further documentation on setting up email in Silverstripe CMS.
Update on the above, Steve checked with TSP and confirmed the following:
By default your environment is configured to send emails from the placeholder domain “no-reply@-.sites.silverstripe.com”; this is configured from the variables section of your environment with the SS_SEND_ALL_EMAILS_FROM environment variable.
This is correct for SC and does not apply to CWP projects (which have the send email defined in YAML code, held in the cwp-installer recipe).
In regards to striking out the existing documentation in https://servicedesk.silverstripe.cloud/support/solutions/articles/75000012863-emails, I'm not sure that there's any real need to do that? It's already linking off to the dev docs for more information. If anything was to change, I'd take out the code snippet to test emails and link to dev docs as the snippet is missing the pretty important $email->send(); from the instructions.
Another reason I wouldn't remove this part of the knowledgebase article is because it references a very platform-specific, default env variable: "You will also have to remove the SS_SEND_ALL_EMAILS_FROM environment variable.". It feels like this isn't something developers using Cloud need to read through the dev docs to know? Feels like that line should stay.
I thought the focus of the AC 'Ensure platform documentation notes that this is supported (and how)' was to make a note of the fact that the underlying infrastructure supports /usr/sbin/sendmail being present and projects are free to use this, as opposed to the legacy built-in PHP mail(). Something which we expected might trip up developers who are managing their own infrastructure if that's not present - so to give Cloud users peace of mind.
If that makes sense, I'd just give TSP a heads up that new projects will now be using the sendmail binary, not the built-in PHP mail() command and check if they think it's worth making a note of this in their docs given Cloud supports sendmail out of the box.
I'd suggest a one line addition to https://servicedesk.silverstripe.cloud/support/solutions/articles/75000012863-emails:
....
# Debugging email
You can search all email sent with logs by using the search query log_type:postfix\/* in your stream. Note that if the email has been successfully sent and not been “bounced”, then we cannot determine the delivery success of the email.
+ [See the Silverstripe CMS developer guides on how email is managed](https://docs.silverstripe.org/en/4/developer_guides/email/#email). The Sendmail transport is recommended for projects and is supported in Silverstripe Cloud.
CWP docs
I couldn't find any existing platforms docs related to email set up on cwp.govt.nz so it doesn't look like there's anything further required for this.
Also, @emteknetnz, I would have expected some notes on this in the upcoming changelog? At least that we recommend updating projects given our docs say "Silverstripe CMS 4 defaults to using the built-in PHP mail() command via a deprecated class Swift_MailTransport. However, using this layer is less secure and is strongly discouraged."
I think we should still remove both the code snippet and the mention of SS_SEND_ALL_EMAILS_FROM as these are both talked about in the dev docs. I'd much prefer we document this in a single location, rather than SC docs + dev docs (+ likely also SCPS docs). A single documented location is far easier to manage. Ensureing that SS_SEND_ALL_EMAILS_FROM is not set is NOT unique to SC, so dev docs makes sense to me.
I'd also double check with TSP re searching logs for postfix - I think that postfix is only used on CWP, not SC
I'd added an AC re updating the changelog
I'd added an AC re updating the changelog
There already was one! :P "Note that the old class is deprecated in the upcoming changelog"
SO, summarising (I'll send this comment to platform team to review):
Following the change for new Silverstripe CMS projects to switch the default mail transport to use the Swift type sendmail binary, not the (now legacy) PHP mail(), there's an infrastructure requirement that something like /usr/sbin/sendmail is present. CMS Squad have confirmed with TSP that this is present on both AWS and Revera platforms, and thought it could be worth noting in the Cloud docs that this is supported out of the box. A change is suggested for the platform team to review:
- Suggest a one line addition to https://servicedesk.silverstripe.cloud/support/solutions/articles/75000012863-emails:
....
# Debugging email
You can search all email sent with logs by using the search query log_type:postfix\/* in your stream. Note that if the email has been successfully sent and not been “bounced”, then we cannot determine the delivery success of the email.
+ [See the Silverstripe CMS developer guides on how email is managed](https://docs.silverstripe.org/en/4/developer_guides/email/#email). The Sendmail transport is recommended for projects and is supported in Silverstripe Cloud.- As an aside, Steve recommended the following change to the same page as it's duplicate information from what's already managed in the open-source docs.
## Configure Silverstripe to use the sender domain for emails
- First, configure your Silverstripe site’s default ‘from’ address for emails, such as password reset emails, by following the administrator emails documentation.
- Then ensure that you send emails from your application with the correct from address:
- $email = new Email('no-reply@example.com', 'user@gmail.com', 'hello', 'email body text');
- For more extensive documentation on how to use the Silverstripe emailer, see the API documentation.
- You will also have to remove the SS_SEND_ALL_EMAILS_FROM environment variable.
+ See the [developer documentation](https://docs.silverstripe.org/en/4/getting_started/#email) for further documentation on setting up email in Silverstripe CMS.- I couldn't find any CWP/ Revera-specific docs for setting up email, so no doc changes have been suggested.
Email documentation has been updated based on provided feedback
https://servicedesk.silverstripe.cloud/support/solutions/articles/75000012863-emails