Add self-hosting email configuration docs + examples, correct SMTP setup for SendGrid/Mailgun-specific setup

2025-03-25 14:05:03 +00:00 · 2022-12-24 11:10:56 -05:00
parent 9d0efc5a22
commit d4bab09927
13 changed files with 122 additions and 26 deletions
--- a/.env.example
+++ b/.env.example
@ -38,10 +38,10 @@ SITE_URL=http://localhost:8080
 # By default, SMTP_HOST is set to smtp.gmail.com, SMTP_PORT is set to 587, SMTP_TLS is set to false, and SMTP_FROM_NAME is set to Infisical
 SMTP_HOST=smtp.gmail.com
 # If STARTTLS is supported, the connection will be upgraded to TLS when SMTP_SECURE is set to false
-SMTP_SECURE=false
-SMTP_PORT=587
 SMTP_USERNAME=
 SMTP_PASSWORD=
+SMTP_PORT=587
+SMTP_SECURE=false
 SMTP_FROM_ADDRESS=
 SMTP_FROM_NAME=Infisical

--- a/backend/src/config/index.ts
+++ b/backend/src/config/index.ts
@ -26,7 +26,7 @@ const POSTHOG_PROJECT_API_KEY =
 const SENTRY_DSN = process.env.SENTRY_DSN!;
 const SITE_URL = process.env.SITE_URL!;
 const SMTP_HOST = process.env.SMTP_HOST! || 'smtp.gmail.com';
-const SMTP_SECURE = process.env.SMTP_SECURE! || false;
+const SMTP_SECURE = process.env.SMTP_SECURE! === 'true' || false;
 const SMTP_PORT = process.env.SMTP_PORT! || 587;
 const SMTP_USERNAME = process.env.SMTP_USERNAME!;
 const SMTP_PASSWORD = process.env.SMTP_PASSWORD!;
--- a/backend/src/integrations/exchange.ts
+++ b/backend/src/integrations/exchange.ts
@ -9,8 +9,7 @@ import {
  INTEGRATION_VERCEL_TOKEN_URL,
  INTEGRATION_NETLIFY_TOKEN_URL,
  INTEGRATION_GITHUB_TOKEN_URL,
-  INTEGRATION_GITHUB_API_URL,
-  ACTION_PUSH_TO_HEROKU
+  INTEGRATION_GITHUB_API_URL
 } from '../variables';
 import {
  SITE_URL,
--- a/backend/src/services/smtp.ts
+++ b/backend/src/services/smtp.ts
@ -1,13 +1,14 @@
 import nodemailer from 'nodemailer';
 import { SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, SMTP_SECURE } from '../config';
+import { SMTP_HOST_SENDGRID, SMTP_HOST_MAILGUN } from '../variables';
 import SMTPConnection from 'nodemailer/lib/smtp-connection';
 import * as Sentry from '@sentry/node';

 const mailOpts: SMTPConnection.Options = {
  host: SMTP_HOST,
-  secure: SMTP_SECURE as boolean,
  port: SMTP_PORT as number
 };
+
 if (SMTP_USERNAME && SMTP_PASSWORD) {
  mailOpts.auth = {
    user: SMTP_USERNAME,
@ -15,6 +16,23 @@ if (SMTP_USERNAME && SMTP_PASSWORD) {
  };
 }

+if (SMTP_SECURE) {
+  switch (SMTP_HOST) {
+    case SMTP_HOST_SENDGRID:
+      mailOpts.requireTLS = true;
+      break;
+    case SMTP_HOST_MAILGUN:
+      mailOpts.requireTLS = true; 
+      mailOpts.tls = {
+        ciphers: 'TLSv1.2'
+      }
+      break;
+    default:
+      mailOpts.secure = true;
+      break;
+  }
+}
+
 export const initSmtp = () => {
  const transporter = nodemailer.createTransport(mailOpts);
  transporter
--- a/backend/src/variables/action.ts
+++ b/backend/src/variables/action.ts
@ -1,5 +0,0 @@
-const ACTION_PUSH_TO_HEROKU = 'pushToHeroku';
-
-export {
-    ACTION_PUSH_TO_HEROKU
-}
--- a/backend/src/variables/index.ts
+++ b/backend/src/variables/index.ts
@ -32,9 +32,9 @@ import {
  GRANTED
 } from './organization';
 import { SECRET_SHARED, SECRET_PERSONAL } from './secret';
-import { PLAN_STARTER, PLAN_PRO } from './stripe';
 import { EVENT_PUSH_SECRETS, EVENT_PULL_SECRETS } from './event';
-import { ACTION_PUSH_TO_HEROKU } from './action';
+import { SMTP_HOST_SENDGRID, SMTP_HOST_MAILGUN } from './smtp';
+import { PLAN_STARTER, PLAN_PRO } from './stripe';

 export {
  OWNER,
@ -44,8 +44,6 @@ export {
  ACCEPTED,
  COMPLETED,
  GRANTED,
-  PLAN_STARTER,
-  PLAN_PRO,
  SECRET_SHARED,
  SECRET_PERSONAL,
  ENV_DEV,
@ -69,6 +67,9 @@ export {
  INTEGRATION_GITHUB_API_URL,
  EVENT_PUSH_SECRETS,
  EVENT_PULL_SECRETS,
-  ACTION_PUSH_TO_HEROKU,
-  INTEGRATION_OPTIONS
+  INTEGRATION_OPTIONS,
+  SMTP_HOST_SENDGRID,
+  SMTP_HOST_MAILGUN,
+  PLAN_STARTER,
+  PLAN_PRO,
 };
--- a/backend/src/variables/smtp.ts
+++ b/backend/src/variables/smtp.ts
@ -0,0 +1,7 @@
+const SMTP_HOST_SENDGRID = 'smtp.sendgrid.net';
+const SMTP_HOST_MAILGUN = 'smtp.mailgun.org';
+
+export {
+    SMTP_HOST_SENDGRID,
+    SMTP_HOST_MAILGUN
+}
--- a/docs/images/email-mailhog-credentials.png
+++ b/docs/images/email-mailhog-credentials.png
--- a/docs/images/email-sendgrid-create-key.png
+++ b/docs/images/email-sendgrid-create-key.png
--- a/docs/images/email-sendgrid-restrictions.png
+++ b/docs/images/email-sendgrid-restrictions.png
--- a/docs/mint.json
+++ b/docs/mint.json
@ -112,7 +112,10 @@
        },
        {
          "group": "Configuration",
-          "pages": ["self-hosting/configuration/envars"]
+          "pages": [
+            "self-hosting/configuration/envars",
+            "self-hosting/configuration/email"
+          ]
        }
      ]
    },
--- a/docs/self-hosting/configuration/email.mdx
+++ b/docs/self-hosting/configuration/email.mdx
@ -0,0 +1,75 @@
+---
+title: "Email Configuration"
+description: ""
+---
+
+Infisical requires you to configure your own SMTP server for certain functionality like:
+
+- Sending email confirmation links to sign up.
+- Sending invite links for projects.
+- Sending alerts.
+
+We strongly recommend using an email service to act as your email server and provide examples for common providers.
+
+## General configuration
+
+By default, you need to configure the following SMTP [environment variables](https://infisical.com/docs/self-hosting/configuration/envars):
+
+- `SMTP_HOST`: Hostname to connect to for establishing SMTP connections.
+- `SMTP_USERNAME`: Credential to connect to host (e.g. team@infisical.com)
+- `SMTP_PASSWORD`: Credential to connect to host.
+- `SMTP_PORT`: Port to connect to for establishing SMTP connections.
+- `SMTP_SECURE`: If `true`, the connection will use TLS when connecting to server with special configs for SendGrid and Mailgun. If `false` (the default) then TLS is used if server supports the STARTTLS extension.
+- `SMTP_FROM_ADDRESS`: Email address to be used for sending emails (e.g. team@infisical.com).
+- `SMTP_FROM_NAME`: Name label to be used in `From` field (e.g. Team).
+
+Below you will find details on how to configure common email providers (not in any particular order).
+
+## Twilio SendGrid
+
+1. Create an account and configure [SendGrid](https://sendgrid.com) to send emails.
+2. Create a SendGrid API Key under Settings > [API Keys](https://app.sendgrid.com/settings/api_keys)
+3. Set a name for your API Key, we recommend using "Infisical," and select the "Restricted Key" option. You will need to enable the "Mail Send" permission as shown below:
+
+![creating sendgrid api key](../../images/email-sendgrid-create-key.png)
+
+![setting sendgrid api key restriction](../../images/email-sendgrid-restrictions.png)
+
+4. With the API Key, you can now set your SMTP environment variables:
+
+```
+SMTP_HOST=smtp.sendgrid.net
+SMTP_USERNAME=apikey
+SMTP_PASSWORD=SG.rqFsfjxYPiqE1lqZTgD_lz7x8IVLx # your SendGrid API Key from step above
+SMTP_PORT=587
+SMTP_SECURE=true
+SMTP_FROM_ADDRESS=hey@example.com # your email address being used to send out emails
+SMTP_FROM_NAME=Infisical
+```
+
+<Info>
+    Remember that you will need to restart Infisical for this to work properly.
+</Info>
+
+## Mailgun
+
+1. Create an account and configure [Mailgun](https://www.mailgun.com) to send emails.
+2. Obtain your Mailgun credentials in Sending > Overview > SMTP
+
+![obtain mailhog api key estriction](../../images/email-mailhog-credentials.png)
+
+3. With your Mailgun credentials, you can now set up your SMTP environment variables:
+
+```
+SMTP_HOST=smtp.mailgun.org # obtained from credentials page
+SMTP_USERNAME=postmaster@example.mailgun.org # obtained from credentials page
+SMTP_PASSWORD=password # obtained from credentials page
+SMTP_PORT=587
+SMTP_SECURE=true
+SMTP_FROM_ADDRESS=hey@example.com # your email address being used to send out emails
+SMTP_FROM_NAME=Infisical
+```
+
+<Info>
+    Remember that you will need to restart Infisical for this to work properly.
+</Info>
--- a/docs/self-hosting/configuration/envars.mdx
+++ b/docs/self-hosting/configuration/envars.mdx
@ -3,9 +3,7 @@ title: "Environment Variables"
 description: ""
 ---

-## The .env file
-
-Configuring Infisical requires setting some environment variables. There is a file called `.env.example` at the root directory of our main repo that you can use to create a `.env` before you start the server.
+Configuring Infisical requires setting some environment variables. There is a file called `.env.example` at the root directory of our main repo that you can use to create a `.env` file before you start the server.

 | Variable                     | Description                                                                                                 | Default Value    |
 | ---------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------- |
@ -22,13 +20,13 @@ Configuring Infisical requires setting some environment variables. There is a fi
 | `MONGO_USERNAME`             | MongoDB username if using container                                                                         | `None`           |
 | `MONGO_PASSWORD`             | MongoDB password if using container                                                                         | `None`           |
 | `SITE_URL`                   | ❗️ Site URL - should be an absolute URL including the protocol (e.g. `https://app.infisical.com`)           | `None`           |
-| `SMTP_HOST`                  | Hostname to connect to for establishing SMTP connections                                                    | `smtp.gmail.com` |
-| `SMTP_SECURE`                | Use TLS when connecting to host. If false, TLS will be used if STARTTLS is supported                        | `false`          |
-| `SMTP_PORT`                  | Port to connect to for establishing SMTP connections                                                     | `587`            |
-| `SMTP_FROM_ADDRESS`          | ❗️ Email address to be used for sending emails (e.g. `team@infisical.com`)                                  | `None`           |
-| `SMTP_FROM_NAME`             | Name label to be used in From field (e.g. `Team`)                                                           | `Infisical`      |
+| `SMTP_HOST`                  | ❗️ Hostname to connect to for establishing SMTP connections                                                    | `smtp.gmail.com` |
 | `SMTP_USERNAME`              | ❗️ Credential to connect to host (e.g. `team@infisical.com`)                                                | `None`           |
 | `SMTP_PASSWORD`              | ❗️ Credential to connect to host                                                                            | `None`           |
+| `SMTP_PORT`                  | Port to connect to for establishing SMTP connections                                                     | `587`            |
+| `SMTP_SECURE`                | If true, use TLS when connecting to host. If false, TLS will be used if STARTTLS is supported                        | `false`          |
+| `SMTP_FROM_ADDRESS`          | ❗️ Email address to be used for sending emails (e.g. `team@infisical.com`)                                  | `None`           |
+| `SMTP_FROM_NAME`             | Name label to be used in From field (e.g. `Team`)                                                           | `Infisical`      |
 | `TELEMETRY_ENABLED`          | `true` or `false`. [More](../overview).                                                                     | `true`           |
 | `CLIENT_ID_HEROKU`           | OAuth2 client ID for Heroku integration                                                                      | `None`           |
 | `CLIENT_ID_VERCEL`           | OAuth2 client ID for Vercel integration                                                                      | `None`           |