portfolio-page/backend/README.md

Portfolio Backend API

A secure Node.js backend API for handling contact form submissions from your portfolio website.

Features

• 🔒 Security: Rate limiting, CORS protection, input validation, spam protection
• 📧 Email Integration: Nodemailer with Gmail/SMTP support
• ✅ Validation: Comprehensive form validation with Joi
• 🚀 Performance: Express.js with async error handling
• 🛡️ Anti-Spam: Honeypot fields and rate limiting
• 📝 Logging: Request/response logging and error tracking
• 🎨 Email Templates: Professional HTML email templates

Setup Instructions

1. Install Dependencies

cd backend
npm install

2. Configure Environment

Copy the example environment file and configure your settings:

cp .env.example .env

Edit .env with your actual configuration:

# Server Configuration
PORT=3001
NODE_ENV=development

# Email Configuration (Gmail example)
EMAIL_SERVICE=gmail
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_SECURE=false
EMAIL_USER=your-email@gmail.com
EMAIL_PASS=your-app-password

# Recipient Configuration
RECIPIENT_EMAIL=your-email@gmail.com
RECIPIENT_NAME=Your Name

# Frontend URL (for CORS)
FRONTEND_URL=http://localhost:5173

# Rate Limiting
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=5

3. Gmail Setup (Recommended)

1. Enable 2-Factor Authentication on your Gmail account
2. Generate App Password:
   • Go to Google Account settings
   • Security → 2-Step Verification → App passwords
   • Generate a password for "Mail"
   • Use this as EMAIL_PASS in your .env file

4. Alternative Email Providers

Outlook/Hotmail:

EMAIL_SERVICE=hotmail
EMAIL_HOST=smtp-mail.outlook.com
EMAIL_PORT=587
EMAIL_SECURE=false

Custom SMTP:

EMAIL_SERVICE=
EMAIL_HOST=your-smtp-host.com
EMAIL_PORT=587
EMAIL_SECURE=false

5. Run the Server

Development:

npm run dev

Production:

npm start

6. Test the API

Visit: http://localhost:3001/health to verify the server is running.

For development, you can test the contact endpoint: http://localhost:3001/api/contact/test

API Endpoints

Health Check

• GET /health - Server health status

Contact Form

• POST /api/contact - Send contact email

Request Body:

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "subject": "Project Inquiry",
  "message": "Hello, I'd like to discuss a project..."
}

Response:

{
  "success": true,
  "message": "Your message has been sent successfully! I'll get back to you soon."
}

Security Features

• Rate Limiting: 5 requests per 15 minutes per IP
• Input Validation: Joi schema validation for all fields
• CORS Protection: Configurable origin restrictions
• Helmet Security: Security headers
• Honeypot Anti-Spam: Hidden field detection
• Request Logging: IP and user agent tracking

Deployment Options

1. Heroku

# Install Heroku CLI, then:
heroku create your-portfolio-api
heroku config:set NODE_ENV=production
heroku config:set EMAIL_USER=your-email@gmail.com
# ... set other environment variables
git push heroku main

2. Railway

# Install Railway CLI, then:
railway login
railway new
railway add
railway up

3. DigitalOcean App Platform

• Create new app from GitHub repository
• Set environment variables in the dashboard
• Deploy automatically

4. Vercel (Serverless)

• Convert Express app to serverless functions
• Deploy with vercel CLI

Environment Variables Reference

Variable	Description	Example
PORT	Server port	3001
NODE_ENV	Environment	production
EMAIL_SERVICE	Email service provider	gmail
EMAIL_HOST	SMTP host	smtp.gmail.com
EMAIL_PORT	SMTP port	587
EMAIL_SECURE	Use SSL/TLS	false
EMAIL_USER	Email username	your@gmail.com
EMAIL_PASS	Email password/app password	app-password
RECIPIENT_EMAIL	Where to send emails	your@gmail.com
RECIPIENT_NAME	Recipient display name	Your Name
FRONTEND_URL	Frontend URL for CORS	https://yoursite.com
RATE_LIMIT_WINDOW_MS	Rate limit window	900000 (15 min)
RATE_LIMIT_MAX_REQUESTS	Max requests per window	5

Troubleshooting

Email Not Sending

1. Check Gmail app password is correct
2. Verify 2FA is enabled on Gmail
3. Check console logs for detailed errors
4. Test with /health endpoint first

CORS Issues

1. Verify FRONTEND_URL matches your frontend domain exactly
2. Include protocol (http/https) in the URL
3. No trailing slashes

Rate Limiting

• Default: 5 requests per 15 minutes per IP
• Adjust RATE_LIMIT_* variables as needed
• Check IP address in logs for debugging

Production Checklist

• Environment variables configured
• Email service tested
• Rate limiting configured
• CORS origins restricted
• SSL/HTTPS enabled
• Error monitoring setup
• Logs configured
• Backup strategy in place

Support

If you encounter issues:

1. Check the console logs
2. Verify your .env configuration
3. Test email configuration with /health endpoint
4. Ensure your email provider allows SMTP access