From 541359b184b45a6745d3304f01702c60b4c3a181 Mon Sep 17 00:00:00 2001 From: James Vasile <james@jamesvasile.com> Date: Tue, 5 Dec 2023 10:52:36 -0500 Subject: [PATCH] Add instructions for ots clients on email and dns --- docs/setup/deployment/email-dns.md | 49 ++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 docs/setup/deployment/email-dns.md diff --git a/docs/setup/deployment/email-dns.md b/docs/setup/deployment/email-dns.md new file mode 100644 index 000000000..5ab650367 --- /dev/null +++ b/docs/setup/deployment/email-dns.md @@ -0,0 +1,49 @@ +# DNS + +In order to operate, Hypha presents two different interfaces. One is a general +website frontend, and the other is the application interface. A future version +of Hypha will remove that general website frontend, so we ignore it in setting +up new Hypha deploys. + +The application interface operates on its own subdomain. Typically, this is +`apply.example.com`. We will provide you with an IP address. We ask that you +add an A record to your DNS configuration so that requests to +`apply.example.com` get routed to that provided IP address. If you prefer, +'apply' can be replaced with another subdomain. + +# Email + +Hypha sends email to its users for password management and other purposes. In +order to accomplish this, it needs to be able to send email from a valid email +address at a valid domain. There are three possible domains for our purposes. +We present them from easiest and most favorable to least desirable. + + * `example.com` - we can send mail from your main domain. The big advantage of + this is that you probably already have mail working for your domain. All you + need to do is create a user account (e.g. `apply@example.com` or + `bot@example.com`) and give us password access to that account. Note that + for gmail-backed email with 2FA enabled, we would need an "App-specific + password" because Hypha cannot do two-factor login into your email. + + * `apply.example.com` - we can send mail from the application interface's + domain. This is clear enogh to users but might require significant setup for + you. We would need you to configure your mail server to send mail from + `apply.example.com` and configure your DNS to validate that mail (via DKIM + and SPF). + + * `opentechstrategies.com` - we can send email from Open Tech Strategies. This + has the benefit of requiring no work on your side to create a valid email + address and provide us with credentials. This has the downside of hypha + emails coming from an unexpected domain, which will confuse users. + +In addition to the above, hypha has support for mailgun. We can delegate +sending mail to mailgun fairly easily. If you are already using mailgun, we'll +hook into it. If not, the additional work of setting up mailgun might not be +worth the effort here. + +Note that no matter what domain Hypha sends from, it is important that email be +configured correctly so it does not often get mis-identified as spam. This +usually requires setting DKIM and SPF records. If you are using gmail-based +email, you probably already have this set, but please check your DNS settings to +make sure. + -- GitLab