182 lines
4.6 KiB
Markdown
182 lines
4.6 KiB
Markdown
# 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)
|
|
|
|
```bash
|
|
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**:
|
|
```bash
|
|
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**:
|
|
```env
|
|
GMAIL_USER=your-email@gmail.com
|
|
GMAIL_APP_PASSWORD=your-16-char-app-password
|
|
SMTP_FROM=your-email@gmail.com
|
|
```
|
|
|
|
### Custom SMTP Server
|
|
|
|
```env
|
|
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:
|
|
|
|
```env
|
|
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
|
|
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
docker-compose exec user-auth env | grep -E "(SMTP|GMAIL|EMAIL)"
|
|
```
|
|
|
|
2. **Test email service directly**:
|
|
```bash
|
|
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**:
|
|
```bash
|
|
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
|