[Closes #434] Adds Mailcatcher to Docker supporting services for local email development (#436)

* Add Mailcatcher to Docker supporting services

* Change default email transport config to smtp to Mailcatcher

* Ran prettier

* Revert "Ran prettier"

This reverts commit 1cb07f2.

* Ran prettier after node_modules removed

* Update README and mock env vars

* Fix formatting

Author: francisli

.env.example

@@ -16,5 +16,9 @@ S3_USER_UPLOADS_ACCESS_KEY_ID=minioadmin
 S3_USER_UPLOADS_SECRET_ACCESS_KEY=minioadmin
 S3_USER_UPLOADS_BUCKET_NAME=compass-files
 
-EMAIL=no.reply.project.compass@gmail.com
-EMAIL_PASS=
+EMAIL_SERVICE=smtp
+EMAIL_AUTH_USER=
+EMAIL_AUTH_PASS=
+EMAIL_FROM=no-reply@compassiep.org
+EMAIL_HOST=localhost
+EMAIL_PORT=1025

README.md

@@ -113,6 +113,35 @@ To update GOOGLE_CLIENT_SECRET:
 
 - Copy the google client secret after creation of the client id
 
+### Email
+
+**Option 1: Use Mailcatcher in Docker**
+
+If you're following _Option 1_ above to run supporting services in Docker, the `.env.example` file is already configured to send email to the Mailcatcher server running on port 1025 for SMTP. The Mailcatcher server will "catch" all email sent and save it in memory to be viewed in its web-based interface running on port 1080. Open it in your web browser at: http://localhost:1080
+
+**Option 2: Configure a live mail server**
+
+If you're not running supporting services in Docker, or wish to test email sending to some test accounts (please take care not to send test emails to real people!), you can configure the following variables in your `.env` file:
+
+1. For an SMTP server
+   ```
+   EMAIL_SERVICE=smtp
+   EMAIL_AUTH_USER=[username for your SMTP server]
+   EMAIL_AUTH_PASS=[password for your SMTP server]
+   EMAIL_FROM=no-reply@compassiep.org
+   EMAIL_HOST=[host name for your SMTP server]
+   EMAIL_PORT=[port for your SMTP server- typically 587 or 465 for secure connections]
+   ```
+2. For a Gmail account
+   ```
+   EMAIL_SERVICE=gmail
+   EMAIL_AUTH_USER=[your Gmail address]
+   EMAIL_AUTH_PASS=[your Gmail password]
+   EMAIL_FROM=[your Gmail address]
+   EMAIL_HOST=
+   EMAIL_PORT=
+   ```
+
 ### Running tests
 
 The database container does not need to be started to run tests, but Docker Desktop must be running in the background.

src/backend/lib/nodemailer.ts

@@ -1,11 +1,18 @@
 import { createTransport } from "nodemailer";
+import SMTPTransport from "nodemailer/lib/smtp-transport";
 import { Env } from "./types";
 
-export const getTransporter = (environment: Env) =>
-  createTransport({
-    service: "gmail",
+export const getTransporter = (env: Env) => {
+  const options: SMTPTransport.Options = {
+    service: env.EMAIL_SERVICE,
     auth: {
-      user: environment.EMAIL,
-      pass: environment.EMAIL_PASS,
+      user: env.EMAIL_AUTH_USER,
+      pass: env.EMAIL_AUTH_PASS,
     },
-  });
+  };
+  if (env.EMAIL_SERVICE === "smtp") {
+    options.host = env.EMAIL_HOST;
+    options.port = parseInt(env.EMAIL_PORT, 10);
+  }
+  return createTransport(options);
+};

src/backend/lib/types/env.ts

@@ -5,6 +5,10 @@ export interface Env {
   S3_USER_UPLOADS_ACCESS_KEY_ID: string;
   S3_USER_UPLOADS_SECRET_ACCESS_KEY: string;
   S3_USER_UPLOADS_BUCKET_NAME: string;
-  EMAIL: string;
-  EMAIL_PASS: string;
+  EMAIL_SERVICE: string;
+  EMAIL_AUTH_USER: string;
+  EMAIL_AUTH_PASS: string;
+  EMAIL_FROM: string;
+  EMAIL_HOST: string;
+  EMAIL_PORT: string;
 }

src/backend/routers/case_manager.ts

@@ -165,7 +165,7 @@ export const case_manager = router({
         req.input,
         req.ctx.db,
         req.ctx.auth.session.user?.name ?? "",
-        req.ctx.env.EMAIL,
+        req.ctx.env.EMAIL_FROM,
         req.input.email,
         req.ctx.env
       );

src/backend/routers/para.ts

@@ -49,7 +49,7 @@ export const para = router({
         req.input,
         req.ctx.db,
         req.ctx.auth.session.user?.name ?? "",
-        req.ctx.env.EMAIL,
+        req.ctx.env.EMAIL_FROM,
         email,
         req.ctx.env
       );

src/backend/tests/fixtures/get-test-server.ts

@@ -38,8 +38,12 @@ export const getTestServer = async (
     S3_USER_UPLOADS_ACCESS_KEY_ID: minio.accessKey,
     S3_USER_UPLOADS_SECRET_ACCESS_KEY: minio.secretKey,
     S3_USER_UPLOADS_BUCKET_NAME: minio.bucket,
-    EMAIL: "example string",
-    EMAIL_PASS: "example string",
+    EMAIL_SERVICE: "smtp",
+    EMAIL_FROM: "no-reply@compassiep.org",
+    EMAIL_AUTH_USER: "", // note that these server settings will not be used, nodemailer is mocked
+    EMAIL_AUTH_PASS: "",
+    EMAIL_HOST: "localhost",
+    EMAIL_PORT: "1025",
   };
 
   // Use statically-built Next.js fixture (if multiple instances of the built-in next() dev server are running, they try to concurrently mutate the same files).

supporting_services/docker-compose.yml

@@ -11,6 +11,12 @@ services:
     volumes:
       - postgres:/var/lib/postgresql/data
 
+  mailcatcher:
+    image: dockage/mailcatcher:0.9.0
+    ports:
+      - "1025:1025"
+      - "1080:1080"
+
   minio:
     image: minio/minio:RELEASE.2023-05-18T00-05-36Z
     ports: