codenuk_backend_mine/services/user-auth/README-EMAIL-SETUP.md

Email Setup for User Auth Service

Overview

The User Auth Service sends verification emails when users register. This document explains how to configure email functionality.

Problem

If emails are not being sent, it's likely due to missing email configuration. The service will show errors like:

• "Email configuration is missing"
• "Failed to create email transporter"
• "Failed to send verification email"

Quick Fix

Option 1: Use the Setup Script (Recommended)

cd automated-dev-pipeline/services/user-auth
./setup-email.sh

This interactive script will guide you through the setup process.

Option 2: Manual Configuration

1. Create .env file:

   cd automated-dev-pipeline/services/user-auth
   cp env.example .env
   

2. Edit .env file with your email credentials

Email Configuration Options

Gmail (Recommended for Development)

1. Enable 2-Step Verification on your Google account
2. Generate App Password:
   • Go to https://myaccount.google.com/security
   • Click "App passwords"
   • Generate password for "Mail"
3. Update .env file:

   GMAIL_USER=your-email@gmail.com
   GMAIL_APP_PASSWORD=your-16-char-app-password
   SMTP_FROM=your-email@gmail.com
   

Custom SMTP Server

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-password
SMTP_FROM=your-email@gmail.com

Development Mode (Mock Emails)

If you don't want to set up real emails in development:

NODE_ENV=development
# No email credentials needed

The service will use mock emails and log what would be sent.

Environment Variables

Variable	Description	Required	Default
GMAIL_USER	Gmail email address	If using Gmail	-
GMAIL_APP_PASSWORD	Gmail app password	If using Gmail	-
SMTP_HOST	SMTP server hostname	If using SMTP	-
SMTP_PORT	SMTP server port	If using SMTP	587
SMTP_USER	SMTP username	If using SMTP	-
SMTP_PASS	SMTP password	If using SMTP	-
SMTP_FROM	From email address	Yes	GMAIL_USER
NODE_ENV	Environment mode	No	development

Testing Email Configuration

1. Check Service Logs

# View email-related logs
docker-compose logs user-auth | grep -E "(Email|SMTP|Gmail|Mock)"

# View all logs
docker-compose logs user-auth

2. Test Registration

1. Visit https://dashboard.codenuk.com/signup
2. Register a new user
3. Check logs for email status

3. Expected Log Output

Success (Real Email):

✅ Email transporter created successfully
📧 Using Gmail configuration
✅ Verification email sent successfully to user@example.com
✉️ Email sent to user@example.com. MessageID: <message-id>

Development Mode (Mock Email):

⚠️ No email configuration found. Using mock transporter for development.
📧 [MOCK] Email would be sent: { to: 'user@example.com', subject: '...', from: '...' }

Troubleshooting

Common Issues

1. "Email configuration is missing"

   • Solution: Set up email credentials in .env file

2. "Authentication failed"

   • Solution: Check username/password, enable 2FA for Gmail

3. "Connection timeout"

   • Solution: Check firewall, use correct port (587 for Gmail)

4. "Invalid credentials"

   • Solution: Use App Password, not regular Gmail password

Debug Steps

1. Check environment variables:

   docker-compose exec user-auth env | grep -E "(SMTP|GMAIL|EMAIL)"
   

2. Test email service directly:

   docker-compose exec user-auth node -e "
   require('dotenv').config();
   const { sendMail } = require('./src/utils/email');
   sendMail('test@example.com', 'Test', 'Test email', '<h1>Test</h1>')
     .then(() => console.log('Email sent'))
     .catch(err => console.error('Email failed:', err.message));
   "
   

3. Verify network connectivity:

   docker-compose exec user-auth ping smtp.gmail.com
   

Security Notes

• Never commit .env files to version control
• Use App Passwords for Gmail, not regular passwords
• Restrict SMTP access to trusted IPs in production
• Rotate credentials regularly

Production Considerations

• Use dedicated email service (SendGrid, Mailgun, etc.)
• Set up proper SPF/DKIM records
• Monitor email delivery rates
• Implement email templates
• Add retry logic for failed emails

Support

If you continue having issues:

1. Check the service logs for detailed error messages
2. Verify your email credentials are correct
3. Test with a simple email client first
4. Check if your email provider blocks automated emails