NestJS Starter Boilerplate 🚀

A production-ready NestJS boilerplate with comprehensive features and best practices for building scalable, enterprise-grade APIs.

⚡️ Quick Start • 🐳 Docker Ready • 🤖 AI/MCP Integrated • ✅ Production Ready

---

🎯 What's Included

Core Features ✅ JWT Authentication (Access/Refresh) ✅ Role-Based Access Control (RBAC) ✅ PostgreSQL + Prisma ORM ✅ Redis Cache & Bull Queues ✅ AWS S3 File Uploads ✅ AWS SES Email Service ✅ Swagger API Documentation ✅ Health Checks & Monitoring

Developer Experience ✅ Docker & Docker Compose ✅ GitHub Actions CI/CD ✅ Jest Testing (90%+ Coverage) ✅ ESLint + Prettier + Husky ✅ Structured Logging (Pino) ✅ Model Context Protocol (MCP) ✅ i18n Multi-language Support

---

📑 Table of Contents

• Features
• Tech Stack
• Quick Start
  • Prerequisites
  • Installation
  • Environment Setup
  • Database Setup
  • Start Development Server
• Environment Configuration
• Docker Setup
• API Documentation
• Model Context Protocol (MCP)
• Testing
• Project Structure
• Development Workflow
• Deployment
• Security Best Practices
• Troubleshooting
• Contributing
• Scripts Reference
• License

---

✅ Implementation Status

This boilerplate is fully production-ready with comprehensive features and best practices:

Feature	Status	Details
JWT Authentication & RBAC	✅ Complete	Access/Refresh tokens, role-based access control
PostgreSQL + Prisma ORM	✅ Complete	Full schema with 3 models (User, Post, PostImage)
Redis Cache & Bull Queues	✅ Complete	Email queue processor, task scheduling
AWS S3 & SES	✅ Complete	File uploads, email templating
Docker & Docker Compose	✅ Complete	Multi-service setup with health checks
GitHub Actions CI/CD	✅ Complete	Automated testing, linting, badge generation
Jest Testing	✅ Complete	18 test suites, 90%+ coverage
MCP Integration	✅ Complete	8 tools, 10 resources, 5 prompts
Swagger Documentation	✅ Complete	Auto-generated API docs
i18n Support	✅ Complete	Multi-language message service

---

✨ Features

• 🔐 Authentication & Authorization - JWT-based auth with access/refresh tokens
• 📚 API Documentation - Auto-generated Swagger/OpenAPI documentation
• 🗄️ Database Integration - PostgreSQL with Prisma ORM
• 📧 Email Service - AWS SES integration with templating
• 📁 File Upload - AWS S3 integration with pre-signed URLs
• 🔄 Background Jobs - Bull queue with Redis for async processing
• 🤖 MCP Integration - Model Context Protocol support for AI tools, resources, and prompts
• 📊 Logging - Structured logging with Pino
• 🧪 Testing - Comprehensive unit tests with Jest (90%+ coverage)
• 🐳 Containerization - Docker and Docker Compose ready
• 🚀 CI/CD - GitHub Actions workflows
• 🔍 Code Quality - ESLint, Prettier, Husky pre-commit hooks
• 📈 Monitoring - Sentry integration for error tracking
• 🚦 Rate Limiting - Built-in request throttling
• 🌐 CORS - Configurable cross-origin resource sharing
• 🔒 Security - Helmet, input validation, and sanitization
• 📝 Internationalization - Multi-language support
• 🎯 Health Checks - Application and database health endpoints

🛠️ Tech Stack

• Framework: NestJS 11.x
• Language: TypeScript 5.9
• Database: PostgreSQL with Prisma ORM 6.x
• Cache/Queue: Redis with Bull 4.x
• Authentication: JWT with Passport
• File Storage: AWS S3
• Email: AWS SES
• Documentation: Swagger/OpenAPI
• Testing: Jest 30.x with SWC
• Logging: Pino (structured JSON logging)
• Validation: class-validator & class-transformer
• MCP Integration: @hmake98/nestjs-mcp for AI capabilities
• Containerization: Docker & Docker Compose

🚀 Quick Start

Prerequisites

• Node.js >= 20.0.0
• Yarn >= 1.22.0
• Docker & Docker Compose (for containerized setup)
• PostgreSQL (if running locally)
• Redis (if running locally)

1. Clone and Install

# Clone the repository
git clone https://github.com/hmake98/nestjs-starter.git
cd nestjs-starter

# Install dependencies
yarn install

2. Environment Setup

# Copy environment template
cp .env.example .env

# Edit the environment file with your configuration
nano .env  # or use your preferred editor

3. Database Setup

# Generate Prisma client
yarn generate

# Run database migrations
yarn migrate

# (Optional) Seed email templates
yarn seed:email

4. Start Development Server

# Development mode with hot reload
yarn dev

# Or using Docker Compose (recommended for full stack)
docker-compose up --build

The API will be available at:

• API: http://localhost:3001
• Documentation: http://localhost:3001/docs
• MCP Playground: http://localhost:3001/mcp/playground (for testing AI tools)

📋 Environment Configuration

Create a .env file based on .env.example template. All environment variables are documented with comments in the template file.

Application Settings

Variable	Description	Default	Required
APP_ENV	Environment mode	local	Yes
APP_NAME	Application name	nestjs-starter	No
APP_DEBUG	Enable debug mode	true	No
APP_LOG_LEVEL	Logging level	debug	No
APP_CORS_ORIGINS	Comma-separated allowed CORS origins	*	No

HTTP Server Configuration

Variable	Description	Default	Required
HTTP_HOST	Server bind address	0.0.0.0	No
HTTP_PORT	Server port	3001	No
HTTP_VERSIONING_ENABLE	Enable API versioning	true	No
HTTP_VERSION	Default API version	1	No

Authentication & JWT

Variable	Description	Example	Required
AUTH_ACCESS_TOKEN_SECRET	JWT access token secret	Generate with openssl rand -base64 32	Yes
AUTH_REFRESH_TOKEN_SECRET	JWT refresh token secret	Generate with openssl rand -base64 32	Yes
AUTH_ACCESS_TOKEN_EXP	Access token expiration	1d (1 day)	No
AUTH_REFRESH_TOKEN_EXP	Refresh token expiration	7d (7 days)	No

Database Configuration

Variable	Description	Example	Required
DATABASE_URL	PostgreSQL connection string	postgresql://user:pass@host:5432/db?schema=public	Yes

AWS Configuration

Variable	Description	Example	Required
AWS_ACCESS_KEY	AWS IAM access key	-	For AWS features
AWS_SECRET_KEY	AWS IAM secret key	-	For AWS features
AWS_S3_REGION	S3 bucket region	us-east-1	For S3 uploads
AWS_S3_BUCKET	S3 bucket name	my-bucket	For S3 uploads
AWS_S3_PRESIGN_LINK_EXPIRES	Pre-signed URL expiration (sec)	1200	No
AWS_SES_REGION	SES service region	us-east-1	For email service
AWS_SES_SOURCE_EMAIL	Verified sender email	no-reply@example.com	For email service

Redis Configuration

Variable	Description	Default	Required
REDIS_HOST	Redis host	redis	Yes
REDIS_PORT	Redis port	6379	No
REDIS_PASSWORD	Redis password	-	No
REDIS_ENABLE_TLS	Enable TLS for Redis	false	No

Model Context Protocol (MCP)

Variable	Description	Default	Required
MCP_SERVER_NAME	MCP server name	nestjs-starter-mcp	No
MCP_SERVER_VERSION	MCP server version	1.0.0	No
MCP_LOG_LEVEL	MCP logging level	info	No

Error Tracking

Variable	Description	Example	Required
SENTRY_DSN	Sentry error tracking DSN	-	No

Quick Setup

# Copy environment template
cp .env.example .env

# Generate JWT secrets
echo "AUTH_ACCESS_TOKEN_SECRET=$(openssl rand -base64 32)" >> .env
echo "AUTH_REFRESH_TOKEN_SECRET=$(openssl rand -base64 32)" >> .env

# Edit remaining values
nano .env

🐳 Docker Setup

Development with Docker Compose

# Start all services (app, database, redis)
docker-compose up --build

# Start only database and Redis (run app locally)
docker-compose up postgres redis

# Run in background
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Production Docker Build

# Build production image (uses ci/Dockerfile for production)
docker build -f ci/Dockerfile -t nestjs-starter:latest .

# Run production container
docker run -p 3001:3001 --env-file .env nestjs-starter:latest

📚 API Documentation

Swagger UI

Visit /docs endpoint when the server is running for interactive API documentation.

Authentication

The API uses JWT Bearer token authentication:

# Login to get tokens
curl -X POST http://localhost:3001/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "password"}'

# Use access token in requests
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  http://localhost:3001/v1/user/profile

Available API Endpoints

Authentication (Public)

• POST /v1/auth/login - User login (email, password)
• POST /v1/auth/signup - User registration
• GET /v1/auth/refresh-token - Refresh access token

User Management (Protected)

• GET /v1/user/profile - Get current user profile
• PUT /v1/user - Update current user profile
• DELETE /v1/admin/user/:id - Delete user (Admin only)

Post Management (Protected)

• POST /v1/post - Create post
• GET /v1/post - List posts with pagination
• PUT /v1/post/:id - Update post (Author only)
• DELETE /v1/post/:id - Delete post (Author only)

Health Check (Public)

• GET /health - Application health status

🤖 Model Context Protocol (MCP) Integration

This boilerplate includes built-in support for the Model Context Protocol (MCP), enabling AI-powered features through tools, resources, and prompts.

What is MCP?

MCP is a standardized protocol for integrating AI capabilities into applications. It allows you to:

• Tools: Execute functions through AI (e.g., calculations, data transformations)
• Resources: Provide data to AI (e.g., documentation, configuration)
• Prompts: Template AI interactions (e.g., code reviews, documentation generation)

MCP Playground

Access the interactive MCP playground at http://localhost:3001/mcp/playground to:

• Test all available tools, resources, and prompts
• View auto-generated schemas
• Execute operations with real-time feedback

Built-in Examples

The boilerplate includes example MCP implementations in src/common/mcp/services/:

Tools (8 implemented)

• Math Operations: add, subtract, multiply, divide
• Text Utilities: toUpperCase, toLowerCase
• System Tools: generateUUID, getCurrentTimestamp

Resources (10 implemented)

• API Documentation: docs://api/overview, docs://api/auth, docs://api/user, docs://api/post
• Server Status: status://server
• Configuration: config://nodeVersion, config://platform, config://environment, config://port

Prompts (5 implemented)

• code-review - Review code for best practices
• generate-api-docs - Generate API documentation
• generate-nestjs-service - Generate NestJS service with CRUD
• optimize-query - Get query optimization suggestions
• generate-unit-tests - Generate Jest test cases

Prompts (AI Templates)

// Code assistance prompts
- code-review        // Review code for best practices
- bug-analysis       // Analyze and suggest bug fixes
- documentation      // Generate documentation
- test-generation    // Generate unit tests

Creating Custom MCP Services

1. Create a Tool Service

// src/modules/your-module/services/mcp.tools.service.ts
import { Injectable } from '@nestjs/common';
import { MCPTool, MCPToolWithParams } from '@hmake98/nestjs-mcp';

@Injectable()
export class YourMCPToolsService {
    // Simple tool (auto-infers parameters from TypeScript types)
    @MCPTool({
        name: 'customTool',
        description: 'Your custom tool description',
    })
    async customTool(params: { input: string }): Promise<string> {
        // Your business logic here
        return `Processed: ${params.input}`;
    }

    // Tool with explicit parameter definitions
    @MCPToolWithParams({
        name: 'complexTool',
        description: 'A more complex tool with explicit params',
        parameters: [
            {
                name: 'userId',
                type: 'string',
                description: 'The user ID to process',
                required: true,
            },
            {
                name: 'options',
                type: 'object',
                description: 'Additional options',
                required: false,
            },
        ],
    })
    async complexTool(params: { userId: string; options?: any }): Promise<any> {
        // Your complex business logic
        return { success: true, userId: params.userId };
    }
}

2. Create a Resource Service

// src/modules/your-module/services/mcp.resources.service.ts
import { Injectable } from '@nestjs/common';
import { MCPResource } from '@hmake98/nestjs-mcp';

@Injectable()
export class YourMCPResourcesService {
    @MCPResource({
        uri: 'data://your-resource',
        name: 'Your Resource',
        description: 'Provides access to your data',
        mimeType: 'application/json',
    })
    async getResource() {
        return {
            uri: 'data://your-resource',
            mimeType: 'application/json',
            text: JSON.stringify({
                data: 'your data',
                timestamp: new Date().toISOString()
            }),
        };
    }
}

3. Create a Prompt Service

// src/modules/your-module/services/mcp.prompts.service.ts
import { Injectable } from '@nestjs/common';
import { MCPPrompt } from '@hmake98/nestjs-mcp';

@Injectable()
export class YourMCPPromptsService {
    @MCPPrompt({
        name: 'customPrompt',
        description: 'Custom AI prompt template',
        arguments: [
            {
                name: 'context',
                description: 'Context for the prompt',
                required: true,
            },
        ],
    })
    async customPrompt(args: { context: string }) {
        return {
            messages: [
                {
                    role: 'user',
                    content: {
                        type: 'text',
                        text: `Given the context: ${args.context}, please provide analysis.`,
                    },
                },
            ],
        };
    }
}

4. Register in Module

// src/modules/your-module/your-module.module.ts
import { Module } from '@nestjs/common';
import { YourMCPToolsService } from './services/mcp.tools.service';
import { YourMCPResourcesService } from './services/mcp.resources.service';
import { YourMCPPromptsService } from './services/mcp.prompts.service';

@Module({
    providers: [
        YourMCPToolsService,
        YourMCPResourcesService,
        YourMCPPromptsService,
    ],
    exports: [
        YourMCPToolsService,
        YourMCPResourcesService,
        YourMCPPromptsService,
    ],
})
export class YourModule {}

MCP services are auto-discovered - no additional registration needed! Just create the services with decorators and they'll automatically appear in the MCP playground.

Configuration

MCP settings can be configured via environment variables:

MCP_SERVER_NAME="your-mcp-server"
MCP_SERVER_VERSION="1.0.0"
MCP_LOG_LEVEL="info"  # debug, info, warn, error

Learn More

• MCP Package Documentation
• MCP Protocol Specification

🧪 Testing

The project uses Jest with SWC for fast test execution. Tests are located in the test/ directory, mirroring the src/ structure.

# Run all tests
yarn test

# Run tests in watch mode (requires manual setup)
jest --config test/jest.json --watch

# Debug tests
yarn test:debug

Test Coverage (18 test suites with 90%+ coverage threshold):

• test/common/ - 11 test suites for shared services (auth, AWS, cache, database, file, helpers, MCP, message)
• test/modules/ - 2 test suites for feature modules (user, post)
• test/workers/ - 1 test suite for email processor
• test/mcp/ - 3 test suites for MCP services (tools, resources, prompts)
• test/mocks/ - Mock data generators using @faker-js/faker

Example Test:

import { Test, TestingModule } from '@nestjs/testing';
import { UserService } from 'src/modules/user/services/user.service';

describe('UserService', () => {
    let service: UserService;

    beforeEach(async () => {
        const module: TestingModule = await Test.createTestingModule({
            providers: [UserService, /* mock dependencies */],
        }).compile();

        service = module.get<UserService>(UserService);
    });

    it('should be defined', () => {
        expect(service).toBeDefined();
    });
});

📁 Project Structure

src/
├── app/                          # Application module and health checks
├── common/                       # Shared modules (14 services)
│   ├── auth/                    # JWT authentication with strategies
│   ├── aws/                     # AWS S3 & SES services
│   ├── cache/                   # Redis cache management
│   ├── config/                  # Configuration management
│   ├── database/                # Prisma ORM integration
│   ├── doc/                     # Documentation decorators
│   ├── file/                    # File upload handling
│   ├── helper/                  # Email, encryption, pagination utilities
│   ├── logger/                  # Pino structured logging
│   ├── mcp/                     # Model Context Protocol (AI integration)
│   │   ├── services/
│   │   │   ├── mcp.tools.service.ts        # Math, text, system tools
│   │   │   ├── mcp.resources.service.ts    # API docs, config resources
│   │   │   └── mcp.prompts.service.ts      # AI prompt templates
│   │   └── mcp.module.ts
│   ├── message/                 # i18n message service
│   ├── request/                 # Guards, decorators, middleware
│   └── response/                # Response formatting, error filters
├── languages/                   # i18n translation files
├── migrations/                  # Database migrations & seeders
├── modules/                     # Feature modules (2 implemented)
│   ├── post/                    # Post CRUD operations
│   │   ├── controllers/         # API endpoints
│   │   ├── services/            # Business logic
│   │   └── dto/                 # Data transfer objects
│   └── user/                    # User management & authentication
│       ├── controllers/         # API endpoints (public & admin)
│       ├── services/            # Business logic
│       └── dto/                 # Data transfer objects
└── workers/                     # Background job processors
    ├── processors/              # Bull queue processors (email)
    └── schedulers/              # Cron jobs (midnight scheduler)

🔧 Development Workflow

Code Quality

# Lint code
yarn lint

# Format code
yarn format

# Type checking
yarn build

Database Operations

# Generate Prisma client after schema changes
yarn generate

# Create new migration
yarn migrate

# Deploy migrations to production
yarn migrate:prod

# Open Prisma Studio
yarn studio

Background Jobs

# Seed email templates
yarn seed:email

# Remove email templates
yarn rollback:email

🚀 Deployment

Docker Production (Recommended)

# Build and tag production image
docker build -f ci/Dockerfile -t your-registry/nestjs-starter:v1.0.0 .

# Push to registry
docker push your-registry/nestjs-starter:v1.0.0

# Run with Docker
docker run -d -p 3001:3001 --env-file .env --name nestjs-app your-registry/nestjs-starter:v1.0.0

# Or deploy with Docker Compose (full stack)
docker-compose up -d --build

Cloud Deployment Examples

AWS ECS

# 1. Create ECR repository
aws ecr create-repository --repository-name nestjs-starter --region us-east-1

# 2. Authenticate Docker to ECR
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin <account-id>.dkr.ecr.us-east-1.amazonaws.com

# 3. Build and push
docker build -f ci/Dockerfile -t nestjs-starter:latest .
docker tag nestjs-starter:latest <account-id>.dkr.ecr.us-east-1.amazonaws.com/nestjs-starter:latest
docker push <account-id>.dkr.ecr.us-east-1.amazonaws.com/nestjs-starter:latest

# 4. Create ECS task definition and service through AWS Console or CLI

Google Cloud Run

# 1. Build and submit to Google Container Registry
gcloud builds submit --tag gcr.io/PROJECT-ID/nestjs-starter

# 2. Deploy to Cloud Run
gcloud run deploy nestjs-starter \
  --image gcr.io/PROJECT-ID/nestjs-starter \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars "APP_ENV=production" \
  --port 3001

DigitalOcean App Platform

# 1. Push to Docker Hub or DigitalOcean Container Registry
docker build -f ci/Dockerfile -t your-dockerhub/nestjs-starter:latest .
docker push your-dockerhub/nestjs-starter:latest

# 2. Create app via DigitalOcean Console
#    - Select Docker Hub as source
#    - Configure environment variables
#    - Add PostgreSQL and Redis managed databases

Heroku

# 1. Login to Heroku
heroku login
heroku container:login

# 2. Create app
heroku create your-app-name

# 3. Add PostgreSQL and Redis addons
heroku addons:create heroku-postgresql:mini
heroku addons:create heroku-redis:mini

# 4. Build and push
docker build -f ci/Dockerfile -t registry.heroku.com/your-app-name/web .
docker push registry.heroku.com/your-app-name/web

# 5. Release
heroku container:release web -a your-app-name

🔐 Security Best Practices

1. Environment Variables: Never commit sensitive data - use .env.example as template only
2. JWT Secrets: Use strong, randomly generated secrets (minimum 32 characters)

   openssl rand -base64 32
   

3. Global Guards: All routes are protected by default (JWT, Roles, Throttler)
4. Password Hashing: Uses Argon2 for secure password storage
5. Rate Limiting: Throttler guard prevents brute force attacks
6. CORS: Configure APP_CORS_ORIGINS to restrict allowed domains
7. Helmet: Security headers configured automatically
8. Input Validation: class-validator validates all DTOs automatically
9. Database: Use connection pooling, read replicas, and prepared statements (Prisma handles this)
10. HTTPS: Always use TLS in production
11. Monitoring: Sentry integration for error tracking and monitoring
12. Soft Deletes: Models support soft deletion to prevent data loss

🔧 Troubleshooting

Common Issues and Solutions

Database Connection Issues

Problem: Error: Can't reach database server

# Check if PostgreSQL is running
docker-compose ps postgres
# or
kubectl get pods -n nestjs-starter | grep postgres

# Check DATABASE_URL format
# Correct: postgresql://username:password@host:5432/database?schema=public

# For Docker: use service name as host
DATABASE_URL="postgresql://postgres:password@postgres:5432/db"

# For local: use localhost
DATABASE_URL="postgresql://postgres:password@localhost:5432/db"

# For Kubernetes: use service name
DATABASE_URL="postgresql://postgres:password@postgres.nestjs-starter.svc.cluster.local:5432/db"

Redis Connection Issues

Problem: Error: Redis connection refused

# Check if Redis is running
docker-compose ps redis
# or
kubectl get pods -n nestjs-starter | grep redis

# Verify REDIS_HOST matches your setup
# Docker: REDIS_HOST=redis
# Local: REDIS_HOST=localhost
# K8s: REDIS_HOST=redis.nestjs-starter.svc.cluster.local

Prisma Migration Errors

Problem: Migration failed or Schema is out of sync

# Reset database (⚠️ DESTRUCTIVE - development only)
docker-compose down -v
docker-compose up -d postgres redis
yarn generate
yarn migrate

# For production, run migrations explicitly
yarn migrate:prod

# If stuck, check migration status
npx prisma migrate status

Port Already in Use

Problem: Error: listen EADDRINUSE: address already in use :::3001

# Find process using the port (macOS/Linux)
lsof -i :3001

# Kill the process
kill -9 <PID>

# Or use a different port
HTTP_PORT=3002 yarn dev

Docker Build Fails

Problem: ERROR [builder X/Y] RUN yarn install --frozen-lockfile

# Clear Docker build cache
docker builder prune -af

# Rebuild without cache
docker-compose build --no-cache

# Check Docker resources (ensure enough memory/disk)
docker system df
docker system prune

JWT Token Issues

Problem: Unauthorized or Invalid token

# Ensure secrets are properly set
echo $AUTH_ACCESS_TOKEN_SECRET
echo $AUTH_REFRESH_TOKEN_SECRET

# Secrets must be the same across restarts
# Use strong random values (min 32 characters)
openssl rand -base64 32

# Check token expiration settings
AUTH_ACCESS_TOKEN_EXP=1d   # 1 day
AUTH_REFRESH_TOKEN_EXP=7d  # 7 days

AWS S3/SES Integration Issues

Problem: AccessDenied or InvalidAccessKeyId

# Verify AWS credentials
aws configure list
aws sts get-caller-identity

# Check IAM permissions for S3
# Required: s3:PutObject, s3:GetObject, s3:DeleteObject

# Check IAM permissions for SES
# Required: ses:SendEmail, ses:SendRawEmail

# Verify email is verified in SES (sandbox mode)
aws ses list-verified-email-addresses

# Check S3 bucket exists and region matches
aws s3 ls s3://your-bucket-name --region us-east-1

Tests Failing

Problem: Tests fail unexpectedly

# Clear test cache
yarn test --clearCache

# Run tests with verbose output
yarn test --verbose

# Run specific test file
yarn test --testPathPattern=user.service.spec.ts

# Check for missing mocks
# Ensure all external dependencies are properly mocked

TypeScript Compilation Errors

Problem: error TS2307: Cannot find module

# Clear build cache and reinstall
rm -rf dist node_modules yarn.lock
yarn install
yarn build

# Regenerate Prisma client
yarn generate

# Check tsconfig.json paths configuration

Memory/Performance Issues

Problem: Application crashes or runs slowly

# Check memory usage
docker stats

# Increase Node.js memory limit
NODE_OPTIONS="--max-old-space-size=4096" yarn start

# Enable garbage collection logs
NODE_OPTIONS="--trace-gc" yarn dev

# Check for memory leaks in production
# Use clinic.js or node --inspect

Kubernetes Pod CrashLoopBackOff

Problem: Pod keeps restarting

# Check pod logs
kubectl logs -f <pod-name> -n nestjs-starter
kubectl logs <pod-name> --previous -n nestjs-starter

# Describe pod for events
kubectl describe pod <pod-name> -n nestjs-starter

# Common causes:
# 1. Missing environment variables
# 2. Database not ready (add init containers)
# 3. Health check failing too quickly (adjust liveness/readiness probes)
# 4. Insufficient resources (increase limits)

# Check events
kubectl get events -n nestjs-starter --sort-by='.lastTimestamp'

Email Not Sending (SES)

Problem: Emails not being sent

# Check SES sandbox mode
# In sandbox, you can only send to verified emails

# Verify sender email
aws ses verify-email-identity --email-address your-email@domain.com

# Check SES sending quota
aws ses get-send-quota

# Check email queue (Bull)
# Visit Bull Board or check Redis
redis-cli KEYS "bull:email:*"

# Check worker logs
docker-compose logs worker

Getting Help

If you encounter issues not covered here:

1. Check Logs: Always start with application logs

   # Docker
   docker-compose logs -f app
   
   # Kubernetes
   kubectl logs -f deployment/nestjs-app -n nestjs-starter
   

2. Enable Debug Mode:

   APP_DEBUG=true
   APP_LOG_LEVEL=debug
   

3. Search Issues: Check GitHub Issues

4. Create an Issue: Provide:

   • Error message
   • Steps to reproduce
   • Environment (Node version, OS, Docker/K8s)
   • Relevant logs

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

Development Guidelines

• Follow TypeScript and ESLint rules
• Write tests for new features
• Update documentation when needed
• Use conventional commit messages
• Ensure all tests pass before submitting PR

📄 Scripts Reference

Script	Description
yarn dev	Start development server with hot reload
yarn build	Build for production
yarn start	Start production server
yarn test	Run unit tests
yarn lint	Lint and fix code
yarn format	Format code with Prettier
yarn generate	Generate Prisma client
yarn migrate	Run database migrations
yarn studio	Open Prisma Studio

🔗 Useful Links

• NestJS Documentation
• Prisma Documentation
• Passport JWT Strategy
• Bull Queue
• Pino Logger
• class-validator
• Docker Documentation
• Model Context Protocol (MCP)
• @hmake98/nestjs-mcp Package

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

Harsh Makwana

• 🌐 GitHub
• 💼 LinkedIn
• 📷 Instagram

🙏 Support

If this project helped you, please consider giving it a ⭐️!

---

Happy Coding! 🎉