217 lines
4.1 KiB
Markdown
217 lines
4.1 KiB
Markdown
# Deployment Guide
|
|
|
|
## 🚀 Quick Deployment
|
|
|
|
### Prerequisites
|
|
1. **Resend API Key** - Get from [resend.com/api-keys](https://resend.com/api-keys)
|
|
2. **Verified Domain** - Verify your domain in Resend dashboard
|
|
3. **Environment Setup** - Copy `.env.example` to `.env`
|
|
|
|
### Environment Configuration
|
|
```env
|
|
# Required
|
|
RESEND_API_KEY=re_your_api_key_here
|
|
FROM_DOMAIN=yourdomain.com
|
|
|
|
# Optional
|
|
FROM_EMAIL=noreply@yourdomain.com
|
|
NODE_ENV=production
|
|
PORT=3001
|
|
RATE_LIMIT_MAX=10
|
|
RATE_LIMIT_WINDOW_MS=900000
|
|
CORS_ORIGIN=https://yourapp.com
|
|
LOG_LEVEL=info
|
|
```
|
|
|
|
## 🐳 Docker Deployment (Recommended)
|
|
|
|
### Quick Start
|
|
```bash
|
|
# Build and run
|
|
docker-compose up -d
|
|
|
|
# Check status
|
|
docker-compose ps
|
|
|
|
# View logs
|
|
docker-compose logs -f email-service
|
|
```
|
|
|
|
### Manual Docker
|
|
```bash
|
|
# Build image
|
|
docker build -t email-service .
|
|
|
|
# Run container
|
|
docker run -d \
|
|
--name email-service \
|
|
-p 3001:3001 \
|
|
--env-file .env \
|
|
email-service
|
|
```
|
|
|
|
## 🖥️ Node.js Deployment
|
|
|
|
### Development
|
|
```bash
|
|
npm install
|
|
npm run server:dev # Backend with hot reload
|
|
npm run dev # Frontend (separate terminal)
|
|
```
|
|
|
|
### Production
|
|
```bash
|
|
npm install --production
|
|
npm run build
|
|
npm start
|
|
```
|
|
|
|
## ☁️ Cloud Deployment
|
|
|
|
### Vercel
|
|
```json
|
|
// vercel.json
|
|
{
|
|
"version": 2,
|
|
"builds": [{ "src": "server.ts", "use": "@vercel/node" }],
|
|
"routes": [{ "src": "/(.*)", "dest": "/server.ts" }]
|
|
}
|
|
```
|
|
|
|
### Railway
|
|
```bash
|
|
railway login
|
|
railway init
|
|
railway up
|
|
```
|
|
|
|
### Heroku
|
|
```bash
|
|
# Procfile
|
|
web: npm start
|
|
|
|
# Deploy
|
|
git push heroku main
|
|
```
|
|
|
|
## 🔧 Configuration
|
|
|
|
### Rate Limiting
|
|
Adjust based on your needs:
|
|
```env
|
|
# Conservative (5 emails per 15 minutes)
|
|
RATE_LIMIT_MAX=5
|
|
RATE_LIMIT_WINDOW_MS=900000
|
|
|
|
# Moderate (20 emails per 10 minutes)
|
|
RATE_LIMIT_MAX=20
|
|
RATE_LIMIT_WINDOW_MS=600000
|
|
|
|
# High volume (100 emails per 5 minutes)
|
|
RATE_LIMIT_MAX=100
|
|
RATE_LIMIT_WINDOW_MS=300000
|
|
```
|
|
|
|
### Security Headers
|
|
The service includes:
|
|
- Content Security Policy
|
|
- HSTS (HTTP Strict Transport Security)
|
|
- X-Frame-Options
|
|
- X-Content-Type-Options
|
|
- Referrer Policy
|
|
|
|
### CORS Configuration
|
|
```env
|
|
# Single origin
|
|
CORS_ORIGIN=https://yourapp.com
|
|
|
|
# Multiple origins (not recommended for production)
|
|
CORS_ORIGIN=https://yourapp.com,https://admin.yourapp.com
|
|
```
|
|
|
|
## 📊 Monitoring
|
|
|
|
### Health Check
|
|
```bash
|
|
curl http://localhost:3001/health
|
|
```
|
|
|
|
Response:
|
|
```json
|
|
{
|
|
"status": "healthy",
|
|
"timestamp": "2026-03-12T10:00:00.000Z",
|
|
"service": "email-template-service",
|
|
"version": "1.0.0"
|
|
}
|
|
```
|
|
|
|
### Logs
|
|
All logs are structured JSON:
|
|
```json
|
|
{
|
|
"level": "info",
|
|
"message": "Email sent successfully",
|
|
"timestamp": "2026-03-12T10:00:00.000Z",
|
|
"meta": {
|
|
"templateId": "invitation",
|
|
"to": "u***@example.com",
|
|
"messageId": "abc123"
|
|
}
|
|
}
|
|
```
|
|
|
|
## 🔍 Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
**"Domain not verified"**
|
|
- Verify domain in Resend dashboard
|
|
- Add SPF record: `v=spf1 include:_spf.resend.com ~all`
|
|
- Add DKIM records (provided by Resend)
|
|
|
|
**"Rate limit exceeded"**
|
|
- Check current limits: `curl http://localhost:3001/api`
|
|
- Adjust `RATE_LIMIT_MAX` in environment
|
|
|
|
**"Email not delivered"**
|
|
- Check Resend logs in dashboard
|
|
- Verify recipient email address
|
|
- Check spam folder
|
|
- Verify SPF/DKIM records
|
|
|
|
**"Validation errors"**
|
|
- Check request format matches API documentation
|
|
- Verify all required fields are provided
|
|
- Check data types (strings, numbers, etc.)
|
|
|
|
### Debug Mode
|
|
```env
|
|
NODE_ENV=development
|
|
LOG_LEVEL=debug
|
|
```
|
|
|
|
## 📋 Production Checklist
|
|
|
|
Before going live:
|
|
- [ ] Environment variables configured
|
|
- [ ] Domain verified in Resend
|
|
- [ ] DNS records added (SPF, DKIM)
|
|
- [ ] SSL certificate installed
|
|
- [ ] Rate limits configured appropriately
|
|
- [ ] CORS origins restricted to your domains
|
|
- [ ] Health checks working
|
|
- [ ] Monitoring/alerting set up
|
|
- [ ] Load testing completed
|
|
|
|
## 🚨 Security Considerations
|
|
|
|
1. **Never expose API keys** in frontend code
|
|
2. **Use environment variables** for all secrets
|
|
3. **Restrict CORS origins** to your domains only
|
|
4. **Monitor rate limits** and adjust as needed
|
|
5. **Keep dependencies updated** regularly
|
|
6. **Use HTTPS** in production
|
|
7. **Monitor logs** for suspicious activity
|
|
|
|
The service is production-ready with enterprise-grade security and reliability! |