Building Scalable Microservices with Node.js and Docker: A Complete Guide

Introduction

As applications grow in complexity, monolithic architectures often become bottlenecks for development teams. Microservices architecture offers a solution by breaking down applications into smaller, independent services that can be developed, deployed, and scaled independently. In this guide, we'll explore how to build a scalable microservices system using Node.js and Docker.

Why Microservices?

Microservices architecture provides several key advantages:

• Independent Deployment: Each service can be deployed without affecting others
• Technology Diversity: Different services can use different technologies
• Scalability: Scale individual services based on demand
• Fault Isolation: Failures in one service don't crash the entire system
• Team Autonomy: Different teams can work on different services independently

Setting Up the Project Structure

Let's start by creating a microservices architecture for an e-commerce platform with three services: User Service, Product Service, and Order Service.

microservices-ecommerce/
├── user-service/
│ ├── src/
│ ├── package.json
│ └── Dockerfile
├── product-service/
│ ├── src/
│ ├── package.json
│ └── Dockerfile
├── order-service/
│ ├── src/
│ ├── package.json
│ └── Dockerfile
├── api-gateway/
│ ├── src/
│ ├── package.json
│ └── Dockerfile
└── docker-compose.yml

Creating a Basic Microservice

Let's create the User Service as an example. First, set up the basic Express.js structure:

// user-service/src/app.js
const express = require('express');
const cors = require('cors');
const helmet = require('helmet');

const app = express();
const PORT = process.env.PORT || 3001;

// Middleware
app.use(helmet());
app.use(cors());
app.use(express.json());

// Health check endpoint
app.get('/health', (req, res) => {
 res.status(200).json({ 
 status: 'healthy', 
 service: 'user-service',
 timestamp: new Date().toISOString()
 });
});

// User routes
app.get('/users', async (req, res) => {
 try {
 // Simulate database call
 const users = [
 { id: 1, name: 'John Doe', email: 'john@example.com' },
 { id: 2, name: 'Jane Smith', email: 'jane@example.com' }
 ];
 res.json(users);
 } catch (error) {
 res.status(500).json({ error: 'Internal server error' });
 }
});

app.get('/users/:id', async (req, res) => {
 try {
 const { id } = req.params;
 // Simulate database call
 const user = { id: parseInt(id), name: 'John Doe', email: 'john@example.com' };
 res.json(user);
 } catch (error) {
 res.status(500).json({ error: 'Internal server error' });
 }
});

app.listen(PORT, () => {
 console.log(`User service running on port ${PORT}`);
});

Dockerizing the Services

Create a Dockerfile for each service to ensure consistent deployment across environments:

# user-service/Dockerfile
FROM node:18-alpine

WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies
RUN npm ci --only=production

# Copy source code
COPY src/ ./src/

# Create non-root user
RUN addgroup -g 1001 -S nodejs
RUN adduser -S nodeuser -u 1001

# Change ownership of the app directory
RUN chown -R nodeuser:nodejs /app
USER nodeuser

EXPOSE 3001

CMD ["node", "src/app.js"]

Service Communication

Microservices need to communicate with each other. Here's an example of the Order Service calling the User Service:

// order-service/src/services/userService.js
const axios = require('axios');

class UserService {
 constructor() {
 this.baseURL = process.env.USER_SERVICE_URL || 'http://user-service:3001';
 }

 async getUserById(userId) {
 try {
 const response = await axios.get(`${this.baseURL}/users/${userId}`, {
 timeout: 5000,
 headers: {
 'Content-Type': 'application/json'
 }
 });
 return response.data;
 } catch (error) {
 if (error.code === 'ECONNREFUSED') {
 throw new Error('User service unavailable');
 }
 throw new Error(`Failed to fetch user: ${error.message}`);
 }
 }
}

module.exports = new UserService();

API Gateway Implementation

An API Gateway acts as a single entry point for all client requests and routes them to appropriate services:

// api-gateway/src/app.js
const express = require('express');
const { createProxyMiddleware } = require('http-proxy-middleware');
const rateLimit = require('express-rate-limit');

const app = express();
const PORT = process.env.PORT || 3000;

// Rate limiting
const limiter = rateLimit({
 windowMs: 15 * 60 * 1000, // 15 minutes
 max: 100 // limit each IP to 100 requests per windowMs
});

app.use(limiter);

// Proxy configuration
const services = {
 users: process.env.USER_SERVICE_URL || 'http://user-service:3001',
 products: process.env.PRODUCT_SERVICE_URL || 'http://product-service:3002',
 orders: process.env.ORDER_SERVICE_URL || 'http://order-service:3003'
};

// Route to services
Object.keys(services).forEach(path => {
 app.use(`/${path}`, createProxyMiddleware({
 target: services[path],
 changeOrigin: true,
 pathRewrite: {
 [`^/${path}`]: '',
 },
 onError: (err, req, res) => {
 res.status(503).json({
 error: 'Service unavailable',
 message: `${path} service is currently unavailable`
 });
 }
 }));
});

app.listen(PORT, () => {
 console.log(`API Gateway running on port ${PORT}`);
});

Docker Compose Configuration

Use Docker Compose to orchestrate all services:

# docker-compose.yml
version: '3.8'

services:
 api-gateway:
 build: ./api-gateway
 ports:
 - "3000:3000"
 environment:
 - USER_SERVICE_URL=http://user-service:3001
 - PRODUCT_SERVICE_URL=http://product-service:3002
 - ORDER_SERVICE_URL=http://order-service:3003
 depends_on:
 - user-service
 - product-service
 - order-service

 user-service:
 build: ./user-service
 environment:
 - PORT=3001
 - DB_HOST=user-db
 depends_on:
 - user-db

 product-service:
 build: ./product-service
 environment:
 - PORT=3002
 - DB_HOST=product-db
 depends_on:
 - product-db

 order-service:
 build: ./order-service
 environment:
 - PORT=3003
 - USER_SERVICE_URL=http://user-service:3001
 - PRODUCT_SERVICE_URL=http://product-service:3002

 user-db:
 image: postgres:15-alpine
 environment:
 POSTGRES_DB: userdb
 POSTGRES_USER: user
 POSTGRES_PASSWORD: password
 volumes:
 - user_data:/var/lib/postgresql/data

 product-db:
 image: postgres:15-alpine
 environment:
 POSTGRES_DB: productdb
 POSTGRES_USER: user
 POSTGRES_PASSWORD: password
 volumes:
 - product_data:/var/lib/postgresql/data

volumes:
 user_data:
 product_data:

Best Practices and Considerations

When implementing microservices, keep these best practices in mind:

• Database per Service: Each service should have its own database to ensure loose coupling
• Circuit Breaker Pattern: Implement circuit breakers to handle service failures gracefully
• Distributed Logging: Use centralized logging solutions like ELK stack for better observability
• Service Discovery: Implement service discovery mechanisms for dynamic service location
• Security: Implement proper authentication and authorization between services

Deployment and Scaling

To deploy and scale your microservices:

# Build and run all services
docker-compose up --build

# Scale specific services
docker-compose up --scale user-service=3 --scale product-service=2

# View running services
docker-compose ps

Conclusion

Microservices architecture with Node.js and Docker provides a robust foundation for building scalable applications. While the initial setup complexity is higher than monolithic applications, the benefits of independent deployment, scaling, and team autonomy make it worthwhile for larger applications. Start small, focus on proper service boundaries, and gradually evolve your architecture as your application grows.