express-jenkins-starter

Production-ready REST API in TypeScript with Express, tested, Dockerized, and integrated into a CI/CD pipeline with Jenkins.

Features

• JWT authentication + role-based access control (admin / user)
• Layered architecture : Routes -> Controllers -> Services -> Repositories -> Models
• Dockerized with multi-stage build + Docker Compose
• 10-stage Jenkins declarative pipeline with manual approval gate
• Jest test suite 25+ cases, 80% coverage enforced in CI
• Helmet, CORS, rate limiting, bcrypt (12 rounds)
• Graceful shutdown on SIGTERM/SIGINT
• Consistent JSON envelope on all responses

Quick Start

Prerequisites

• Node.js 20+
• MongoDB locally or via Docker

# Install
npm ci

# Configure
cp .env.example .env

# Start MongoDB (if not running)
docker run -d -p 27017:27017 --name mongo mongo:7.0-jammy

# Seed (optional)
npx ts-node scripts/seed.ts

# Dev server (hot reload)
npm run dev

API -> http://localhost:3000/api/v1

Docker Compose

# Full stack (API + MongoDB)
docker-compose up -d

# With Mongo Express UI (port 8081)
docker-compose --profile tools up -d

# Logs
docker-compose logs -f api

# Stop
docker-compose down

Production

docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

# Or manually
docker build -t express-api:latest .
docker run -p 3000:3000 --env-file .env express-api:latest

Environment Variables

API Reference

Base URL: http://localhost:3000/api/v1

Health

Users

Examples

# Register
curl -X POST http://localhost:3000/api/v1/users/register \
  -H "Content-Type: application/json" \
  -d '{"name":"Alice","email":"alice@example.com","password":"Password1"}'

# Login
curl -X POST http://localhost:3000/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{"email":"alice@example.com","password":"Password1"}'

# Profile
curl http://localhost:3000/api/v1/users/me \
  -H "Authorization: Bearer <token>"

# List users (admin)
curl "http://localhost:3000/api/v1/users?page=1&limit=10&search=alice" \
  -H "Authorization: Bearer <admin_token>"

Response Format

{
  "success": true,
  "message": "Users retrieved",
  "data": [],
  "meta": { "page": 1, "limit": 10, "total": 42, "totalPages": 5 }
}

{
  "success": false,
  "message": "Validation failed",
  "errors": [{ "field": "email", "msg": "Valid email required" }]
}

Testing

npm test                          # All tests + coverage
npm run test:watch                # Watch mode
npx jest tests/user.test.ts       # Single file

Coverage enforced in CI: 80% lines / 75% functions

CI/CD — Jenkins Pipeline

10-stage declarative pipeline defined in Jenkinsfile:

Required Jenkins Credentials

Architecture

src/ ├── config/ # Env, DB connection ├── middleware/ # Auth, error handler, rate limit ├── modules/ │ └── users/ │ ├── user.model.ts │ ├── user.repository.ts │ ├── user.service.ts │ ├── user.controller.ts │ └── user.routes.ts ├── utils/ # AppError, logger, response helpers └── app.ts

Error handling: AppError carries HTTP status. Global errorHandler catches all errors including Mongoose/MongoDB driver errors.

Seed Data

npx ts-node scripts/seed.ts

License

MIT