diff --git a/.env.example b/.env.example index 932846bfe0..dea42a19c5 100644 --- 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 diff --git a/backend/src/config/index.ts b/backend/src/config/index.ts index 43a9026ac3..6953f75278 100644 --- 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!; diff --git a/backend/src/integrations/exchange.ts b/backend/src/integrations/exchange.ts index dafddc7853..cb0ff84e01 100644 --- 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, diff --git a/backend/src/services/smtp.ts b/backend/src/services/smtp.ts index 14d5434395..12841eee7d 100644 --- 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 diff --git a/backend/src/variables/action.ts b/backend/src/variables/action.ts deleted file mode 100644 index 1f913bbe9b..0000000000 --- a/backend/src/variables/action.ts +++ /dev/null @@ -1,5 +0,0 @@ -const ACTION_PUSH_TO_HEROKU = 'pushToHeroku'; - -export { - ACTION_PUSH_TO_HEROKU -} \ No newline at end of file diff --git a/backend/src/variables/index.ts b/backend/src/variables/index.ts index c69ed8176d..e284d6d5c7 100644 --- 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, }; diff --git a/backend/src/variables/smtp.ts b/backend/src/variables/smtp.ts new file mode 100644 index 0000000000..4db7c9f121 --- /dev/null +++ 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 +} \ No newline at end of file diff --git a/docs/images/email-mailhog-credentials.png b/docs/images/email-mailhog-credentials.png new file mode 100644 index 0000000000..8d5a112956 Binary files /dev/null and b/docs/images/email-mailhog-credentials.png differ diff --git a/docs/images/email-sendgrid-create-key.png b/docs/images/email-sendgrid-create-key.png new file mode 100644 index 0000000000..1caa977a8e Binary files /dev/null and b/docs/images/email-sendgrid-create-key.png differ diff --git a/docs/images/email-sendgrid-restrictions.png b/docs/images/email-sendgrid-restrictions.png new file mode 100644 index 0000000000..a70891a60b Binary files /dev/null and b/docs/images/email-sendgrid-restrictions.png differ diff --git a/docs/mint.json b/docs/mint.json index 92a952767e..f12a2c2e41 100644 --- 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" + ] } ] }, diff --git a/docs/self-hosting/configuration/email.mdx b/docs/self-hosting/configuration/email.mdx new file mode 100644 index 0000000000..99ab387c7c --- /dev/null +++ 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 +``` + + + Remember that you will need to restart Infisical for this to work properly. + + +## 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 +``` + + + Remember that you will need to restart Infisical for this to work properly. + \ No newline at end of file diff --git a/docs/self-hosting/configuration/envars.mdx b/docs/self-hosting/configuration/envars.mdx index 8bbb507d84..a66f641fc8 100644 --- 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` |