From a001fc1b5718f47725fc339d5db3a6c24a14519c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nuno=20G=C3=B3is?= Date: Tue, 14 Nov 2023 12:53:34 +0000 Subject: [PATCH] docs: troubleshooting email service (#5333) https://linear.app/unleash/issue/SR-173/discussion-question-notification-from-email-doesnt-work Adds a troubleshooting guide for [email service](https://docs.getunleash.io/using-unleash/deploy/email-service), which includes some knowledge shared in this discussion: https://github.com/orgs/Unleash/discussions/5323#discussioncomment-7554431 --- .../using-unleash/deploy/email-service.md | 4 +++ .../troubleshooting/email-service.md | 35 +++++++++++++++++++ website/sidebars.js | 1 + 3 files changed, 40 insertions(+) create mode 100644 website/docs/using-unleash/troubleshooting/email-service.md diff --git a/website/docs/using-unleash/deploy/email-service.md b/website/docs/using-unleash/deploy/email-service.md index 1366c44ca5..ed88bfef76 100644 --- a/website/docs/using-unleash/deploy/email-service.md +++ b/website/docs/using-unleash/deploy/email-service.md @@ -46,3 +46,7 @@ unleash.start({ }, }); ``` + +## Troubleshooting {#troubleshooting} + +For troubleshooting tips, please refer to the [email service troubleshooting guide](../troubleshooting/email-service.md). diff --git a/website/docs/using-unleash/troubleshooting/email-service.md b/website/docs/using-unleash/troubleshooting/email-service.md new file mode 100644 index 0000000000..69d5bb04a8 --- /dev/null +++ b/website/docs/using-unleash/troubleshooting/email-service.md @@ -0,0 +1,35 @@ +--- +title: The email service is not working correctly on my self-hosted Unleash instance +--- + +When setting up your self-hosted Unleash instance, one of the available options is to configure an [email service](https://docs.getunleash.io/using-unleash/deploy/email-service) that will allow Unleash to send reset password and welcome emails to users. + +Here's how to troubleshoot some common issues related to the email service. + +## Configuration + +The most common issues arise from misconfiguration. Please refer to the following documentation for guidance: +- [Email service](https://docs.getunleash.io/using-unleash/deploy/email-service) +- [Configuring Unleash](https://docs.getunleash.io/using-unleash/deploy/configuring-unleash) + +You should double check that the details in your configuration look correct. + +## Invalid URL error + +Make sure that the [UNLEASH_URL](https://docs.getunleash.io/using-unleash/deploy/configuring-unleash#unleash-url) variable is correctly set to a valid URL. This should be set to the public discoverable URL of your Unleash instance, and it should include the protocol (http or https). + +Examples: +- Subdomain: `https://unleash.mysite.com` +- Subpath: `https://mysite.com/unleash` + +## SSL-related errors + +### SMTP TLS port + +Please double check that you're trying to reach your SMTP server on the TLS port, typically `587`. + +### Custom SSL certificate + +If you're using your own SMTP server which uses a custom SSL certificate, you will need to tell Unleash to trust that certificate. You can do this by setting the [NODE_EXTRA_CA_CERTS](https://docs.getunleash.io/using-unleash/deploy/configuring-unleash#node-extra-ca-certs) variable to the path of the certificate file. + +This is usually done by mounting the custom certificate in a volume, and then setting `NODE_EXTRA_CA_CERTS` to the absolute path in the container where it can find the certificate. For example, if you mount it to `/var/certs`, you should set `NODE_EXTRA_CA_CERTS` to something like `/var/certs/mycert.crt`. diff --git a/website/sidebars.js b/website/sidebars.js index c6640217b8..aac54593fe 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -416,6 +416,7 @@ module.exports = { }, items: [ 'using-unleash/troubleshooting/cors', + 'using-unleash/troubleshooting/email-service', 'using-unleash/troubleshooting/feature-not-available', 'using-unleash/troubleshooting/flag-exposure', 'using-unleash/troubleshooting/flag-not-returned',