A Comprehensive, Microservices-Based API for Managing Budgets, Expenses, Users, and So Much More!

Welcome to the Budget Management API, a robust, microservices backend platform for managing budgets, expenses, users, orders, and notifications. Built with Node.js, Express, and TypeScript, it supports advanced features like GraphQL, gRPC, WebSockets, and REST APIs.

The API also integrates with PostgreSQL, MongoDB, MySQL, Redis, RabbitMQ, Kafka, and Elasticsearch, and is containerized with Docker and orchestrated using Kubernetes that fully supports zero-downtime deployment (blue/green & canary deployment). It also includes a developer-friendly CLI tool and interactive Swagger/OpenAPI documentation for exploring and testing endpoints.

Below is a very comprehensive guide to setting up, running, and utilizing this API! 💸🚀

1. Overview
2. Live Deployment
3. Technologies Used
   • Microservices Architecture
   • Microservices Diagram
   • Full Architecture Diagram
4. Project Structure
5. Setup Instructions
6. Available Endpoints
7. Schemas
8. Features and Integrations
9. Environment Variables
10. CLI Usage
11. Demo Frontend UI
12. Swagger Documentation
13. GraphQL Integration
14. NGINX Configuration
15. gRPC Integration
16. Dockerization
17. Kubernetes Deployment
18. Spring Boot Backends with Gradle & Maven
19. Dotnet Backends with C#
20. Continuous Integration and Deployment with Jenkins
    • GitHub Actions
21. Testing
22. Contributing
23. Author

The Budget Management API is designed to handle complex budget management requirements, including:

• Budget and expense tracking.
• User management and authentication (JWT/password and passwordless passkeys via WebAuthn).
• Real-time notifications via WebSockets.
• Asynchronous task handling using RabbitMQ and Kafka.
• Advanced search capabilities with Elasticsearch.
• CLI operations for direct interaction with the system.
• Compatibility with modern cloud environments like Docker and Kubernetes.
• Support for both REST and GraphQL APIs for flexible data access.
• Sample dotnet and spring-boot backends to demonstrate integration with other technologies.
• ...and so much more!

The purpose of this API is to demonstrate the capabilities of modern backend technologies and provide a foundation for building scalable, real-time applications. It can be used as a reference for developers looking to implement similar features in their projects. Simply clone the repository, set up the environment, and start building the frontend or additional functionality on top of the existing API!

The Budget Management API is deployed live at https://budget-management-backend-api.onrender.com.

Additionally, a mock frontend UI is also available, hosted at https://budget-manage-app.vercel.app.

You can access the API and test the endpoints directly from the browser. Feel free to use the API for your own projects or applications. Simply add some attribution to the original repository and the creator. Also, be sure that you use your own credentials and tokens, otherwise your data may clash with mine and other users' data!

The Budget Management API is designed with a microservices architecture, allowing for modular development and deployment. Each service can be developed, deployed, and scaled independently, providing flexibility and resilience.

1. Authentication/User Service: Handles user registration, login, and JWT token management (+ profile management as well).
2. Budget Service: Manages budgets, including creation, updates, and retrieval.
3. Expense Service: Manages expenses associated with budgets, including CRUD operations.
4. Customer Service: Manages customer data, including creation and updates.
5. Search Service: Provides advanced search capabilities using Elasticsearch.
6. Order Service: Manages orders, including creation and updates.
7. Transaction Service: Logs transactions for budgets and expenses.
8. Notification Service: Sends real-time notifications to users via WebSockets.
9. Task Management Service: Handles asynchronous tasks using RabbitMQ and Kafka.

This architecture allows for easy integration of additional services, such as order management, task management, and notification services, without affecting the core functionality of the API.

Each service communicates with others using RabbitMQ for asynchronous messaging, gRPC for high-performance remote procedure calls, and REST APIs for standard HTTP communication. This ensures that services can operate independently while still being able to interact with each other as needed.

Also, the API is designed to be modular, allowing for easy addition of new services or features without disrupting existing functionality. This modularity is achieved through the use of separate directories for each service, with shared utilities and configurations in a common structure.

%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#4CAF50','primaryTextColor':'#fff','primaryBorderColor':'#2E7D32','lineColor':'#1976D2','secondaryColor':'#2196F3','tertiaryColor':'#FFC107','fontSize':'14px','fontFamily':'Arial'}}}%%
mindmap
  root((Budget Management API))
    Root Files
      .env[.env — Environment variables]
      .env.example[.env.example — Sample config]
      .gitignore[.gitignore — Git ignore]
      .prettierrc[.prettierrc — Code formatter]
      LICENSE[LICENSE — License]
      README[README.md — Documentation]
      cli.js[cli.js — CLI tool]
      docker-compose.yml[docker-compose.yml — Docker config]
      Dockerfile[Dockerfile — Container image]
      grpcServer.js[grpcServer.js — gRPC server]
      index.js[index.js — App entry point]
      nodemon.json[nodemon.json — Dev config]
      openapi.yaml[openapi.yaml — API spec]
      package.json[package.json — NPM config]
      prometheus.yml[prometheus.yml — Monitoring]
      start.sh[start.sh — Startup script]
    Tests
      __tests__[__tests__/app.test.js — Main tests]
    Docs
      swaggerConfig[docs/swaggerConfig.js — Swagger]
    GraphQL
      schema[graphql/schema.js — Schema]
    Proto
      budget[proto/budget.proto — gRPC proto]
    NGINX
      docker-compose[nginx/docker-compose.yml]
      Dockerfile[nginx/Dockerfile]
      nginx.conf[nginx/nginx.conf — Reverse proxy]
      start_nginx[nginx/start_nginx.sh]
      README[nginx/README.md]
    Redis-Mongo Flow
      app[redis-mongo-flow/app.js]
      config[redis-mongo-flow/config.js]
      package[redis-mongo-flow/package.json]
      README[redis-mongo-flow/README.md]
      seed[redis-mongo-flow/seed.js]
      test[redis-mongo-flow/test.js]
    Round Robin
      config[round-robin/config.js]
      index[round-robin/index.js]
      README[round-robin/README.md]
    Services
      dataSeeder[dataSeeder.js — MongoDB seeder]
      elastic[elasticService.js — Elasticsearch]
      jwt[jwtService.js — JWT helpers]
      postgres[postgresService.js — PostgreSQL]
      rabbitMQ[rabbitMQService.js — RabbitMQ]
      redis[redisService.js — Redis]
      websocket[websocketService.js — WebSocket]
    Controllers
      auth[authController.js — Auth]
      budget[budgetController.js — Budget]
      customer[customerController.js — Customer]
      expense[expenseController.js — Expense]
      notification[notificationController.js — Notifications]
      order[orderController.js — Order]
      search[searchController.js — Search]
      task[taskController.js — Task]
      transaction[transactionController.js — Transaction]
      user[userController.js — User]
    Middleware
      authMiddleware[authMiddleware.js — JWT auth]
    Models
      budget[budget.js — Budget schema]
      customer[customer.js — Customer schema]
      expense[expense.js — Expense schema]
      order[order.js — Order schema]
      task[task.js — Task schema]
      user[user.js — User schema]
    Routes
      auth[authRoutes.js — Auth]
      budget[budgetRoutes.js — Budget]
      customer[customerRoutes.js — Customer]
      expense[expenseRoutes.js — Expense]
      graphql[graphqlRoutes.js — GraphQL]
      index[index.js — Router entry]
      notification[notificationRoutes.js — Notifications]
      order[orderRoutes.js — Order]
      search[searchRoutes.js — Search]
      task[taskRoutes.js — Task]
      transaction[transactionRoutes.js — Transaction]
      user[userRoutes.js — User]
    Views
      icons[android/apple/favicon icons]
      home[home.html — Homepage]
      manifest[manifest.json — Web manifest]
    Other
      more[Additional files and directories]

• Node.js (>= 16)
• Docker and Docker Compose (if using containerized setup)
• MongoDB, PostgreSQL, MySQL, RabbitMQ, Redis, and Elasticsearch services.

1. Clone the repository:

   git clone https://github.com/hoangsonww/Budget-Management-Backend-API.git
   cd Budget-Management-Backend-API

2. Install dependencies:

   npm install

3. Set up environment variables:

• Create a .env file in the root directory:

  MONGO_DB_URI=mongodb://localhost:27017/budget_manager
  POSTGRES_URI=postgres://user:password@localhost:5432/budget_manager
  REDIS_URL=redis://localhost:6379
  RABBITMQ_URL=amqp://localhost
  KAFKA_BROKER=localhost:9092
  JWT_SECRET=your_secret_key

• Replace placeholders with your actual configuration.

4. Start the application:

   npm start

5. Access the application:

• API: http://localhost:3000
• Swagger: http://localhost:3000/docs

Endpoints marked (auth) require a valid JWT in the Authorization: Bearer <token> header. The two passkey login endpoints are public (they form the passwordless sign-in flow), while passkey registration and management require an existing session so a logged-in user can enroll and manage their own credentials.

Additionally, the root / endpoint provides a welcome message and information about the API.

More endpoints and features are available in the API. Refer to the Swagger documentation for detailed information.

A single WebAuthn credential. A user may own many passkeys. Security-critical fields (credentialID, publicKey, counter) never leave the server; only the metadata below is exposed to the management UI.

• High-performance RPC framework.
• Start the gRPC server using:

  npm start

• Flexible data queries and mutations.
• Access the GraphQL endpoint at http://localhost:3000/graphql.

• Real-time notifications for clients.
• Notifications can be sent using the /api/notifications endpoint or CLI.

• Build and run the app with Docker:

  docker-compose up --build

• Advanced search for expenses.
• Search endpoint: /api/search/expenses.

• Asynchronous task handling.
• Use the budget-manager CLI to add tasks.
• Tasks are processed in the background.

• Distributed event streaming platform.
• Kafka broker URL: localhost:9092.
• Kafka producer and consumer are integrated.

• In-memory caching for improved performance.
• Redis URL: redis://localhost:6379.
• Caching is used for user sessions and other data.
• Also stores short-lived (5 min), single-use WebAuthn challenges for the passkey ceremonies.

• Passwordless, phishing-resistant authentication built on the WebAuthn standard, implemented with @simplewebauthn on both the server and the browser.
• Passwordless login uses discoverable credentials, so users can sign in without typing an email — the browser offers any passkey registered for the site. A successful ceremony returns a standard JWT, identical to password login.
• Registration & management are protected: a logged-in user can enroll multiple passkeys and list/rename/delete them. Registration via /api/auth/register auto-logs-in (returns a JWT) so new users can immediately enroll a passkey.
• Two-step ceremonies: the client first requests options from the server, hands them to the authenticator, then posts the result back to verify. Challenges are kept in Redis with a short TTL and consumed on use.
• Relying-Party (RP) resolution is per-request: the rpID/origin are derived from the request's Origin header (great for local dev where the frontend runs on http://localhost:3000). In production set WEBAUTHN_ORIGINS (and optionally RP_ID/RP_NAME) to lock ceremonies to an allowlist of trusted origins.
• Friendly names are auto-derived from the authenticator's AAGUID/transports (e.g. "iCloud Keychain", "Windows Hello", "YubiKey 5 Series", "This device").
• Endpoints live under /api/passkeys — see the Available Endpoints table.

• Relational database for transaction logs.
• PostgreSQL URL: postgres://user:password@localhost:5432/budget_manager.
• Used for storing transaction logs and other relational data.
• MySQL is also supported as an alternative.

• Primary NoSQL database for managing budgets and expenses.
• MongoDB URL: mongodb://localhost:27017/budget_manager.
• Used for storing budgets, expenses, and user data.

• Reverse proxy and load balancer.
• Nginx configuration is included in the nginx directory.
• Load balancing can be configured for multiple instances.
• SSL termination and caching can be added.

• Deployment manifests are available in the kubernetes directory.
• Deploy the application to a Kubernetes cluster using:

  kubectl apply -f kubernetes/

• Monitoring and observability tools.
• Prometheus configuration is available in prometheus.yml.
• Grafana can be used for visualization and monitoring.
• Metrics and dashboards can be configured.
• Monitor the health and performance of the API.

The Budget Management API interacts with various services and databases to provide a comprehensive backend solution. The architecture includes a frontend UI, a CLI tool, an API gateway, a gRPC server, and multiple external services. Here is a high-level overview of the service interaction:

flowchart LR
    FE[Frontend UI<br/>]
    CLI[CLI Tool / gRPC Clients]
    APIGW[API Gateway / Express.js]
    GRPC[gRPC Server]
    CORE[Application Core<br/>Controllers & Services]
    Mongo[MongoDB]
    Postgres[PostgreSQL]
    Elastic[Elasticsearch]
    Redis[Redis Cache]
    Queue[RabbitMQ / Kafka Queue]
    Stream[Kafka Event Streaming]
    External[External Services<br/>Email, SMS, etc.]

    FE -->|HTTP / GraphQL requests| APIGW
    CLI -->|CLI commands / gRPC calls| GRPC
    APIGW <--> GRPC
    APIGW -->|REST / WebSocket / GraphQL| CORE
    GRPC --> CORE

    CORE --> Mongo
    CORE --> Postgres
    CORE --> Elastic
    CORE --> Redis
    CORE --> Queue
    CORE --> Stream
    Queue -->|Asynchronous tasks| External
    Stream -->|Event-driven actions| External

Ensure your .env file looks like this before getting started:

# Server Configuration
PORT=

# MongoDB Configuration
MONGO_DB_URI=
MONGO_DB_USERNAME=
MONGO_DB_PASSWORD=

# Redis Configuration
REDIS_HOST=
REDIS_PORT=
REDIS_URL=

# RabbitMQ Configuration
RABBIT_MQ_HOST=
RABBITMQ_URL=

# Kafka Configuration
KAFKA_BROKER=

# JWT Secret Key
JWT_SECRET=

# WebAuthn / Passkey Configuration
# RP_ID: the registrable domain passkeys are bound to (e.g. example.com).
#   Leave blank to derive it from the request origin (good for local dev,
#   where the frontend on http://localhost:3000 resolves to rpID "localhost").
RP_ID=
# RP_NAME: human-readable relying-party name shown in the OS passkey prompt.
RP_NAME=
# WEBAUTHN_ORIGINS: comma-separated allowlist of frontend origins permitted to
#   perform passkey ceremonies (e.g. https://app.example.com,http://localhost:3000).
#   Leave blank to trust the request origin (local dev convenience).
WEBAUTHN_ORIGINS=

# Elasticsearch Configuration
ELASTIC_SEARCH_URL=

# PostgreSQL Configuration
POSTGRES_URL=

The budget-manager CLI provides a convenient way to interact with the application from the command line.

Follow these steps to use the CLI:

1. Install globally:

   npm link

2. Use commands:

   budget-manager seed
   budget-manager notify "Hello!"
   budget-manager add-task "Task description"

3. View available commands:

    budget-manager --help

This will display a list of available commands and options:

budget-manager --help
Usage: budget-manager [options] [command]

A CLI for managing budgets, tasks, orders, and more.

Options:
  -V, --version                        output the version number
  -h, --help                           display help for command

Commands:
  seed                                 Seed the MongoDB database with initial data
  notify <message>                     Send a real-time notification to WebSocket clients
  list-budgets                         List all budgets in the database
  add-task <description>               Add a new task to the task queue
  list-orders                          List all orders in the database
  add-order <customerId> <amount>      Add a new order
  list-customers                       List all customers in the database
  add-customer <name> <email> [phone]  Add a new customer
  search-expenses <query>              Search for expenses using a query
  graphql-query <query>                Perform a GraphQL query
  help [command]                       display help for command

Examples:
  $ budget-manager seed
  $ budget-manager notify "Hello World!"
  $ budget-manager list-budgets
  $ budget-manager add-task "New Task Description"

4. View version information:

   budget-manager --version

The CLI provides a simple way to interact with the backend API and perform various operations. It can be used for testing, debugging, and managing the application without a frontend interface or using the Swagger documentation.

The Budget Management API includes a demo frontend UI for interacting with the backend.

It gives developers an idea of how the API can be used in a real-world application. The frontend UI is built using React, Redux, and Material-UI components.

To run the frontend UI, follow these steps:

1. Navigate to the frontend directory:

   cd frontend

2. Install dependencies: (use npm install --legacy-peer-deps if you encounter peer dependency issues)

    npm install

3. Start the development server:

   npm start

4. Access the frontend UI at http://localhost:3001 (or whichever port is specified in the console).

Alternatively, it is also deployed live at https://budget-manage-app.vercel.app. Feel free to use the live version for testing and exploration.

For more information, refer to the Frontend README in the frontend directory to learn about the frontend UI components, features, and usage.

Here are some screenshots of the frontend UI:

Home:

Dashboard:

Budgets:

Expenses:

Profile:

Passkeys:

Login:

Register:

Users:

• Comprehensive API documentation is available at /docs.
• Includes all endpoints, schemas, and examples.
• Use Swagger UI to test and interact with the API.
• The Swagger UI looks like this:

• The Budget Management API supports GraphQL queries and mutations.
• Access the GraphQL endpoint at http://localhost:3000/api/graphql.
• Use the GraphiQL interface to interact with the API.
• The GraphiQL interface looks like this:

• Interact with the API using GraphQL queries and mutations. Examples include:

query {
  budgets {
    id
    name
    limit
    createdAt
  }
}

Or:

query {
  expenses(budgetId: "64c9f8f2a73c2f001b3c68f4") {
    id
    description
    amount
    budgetId
    createdAt
  }
}

When you run these queries, you will receive a response with the requested data. GraphQL provides a flexible and efficient way to fetch and manipulate data from the backend. Here is an example:

• The nginx directory contains an Nginx configuration for reverse proxy and load balancing.
• Use Nginx to route requests to multiple instances of the API.
• Configure SSL termination and caching for improved performance.
• The Nginx configuration looks like this:

server {
    listen 80;
    server_name localhost;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

• For more information, refer to the Nginx documentation and the Nginx Directory.

The Budget Management API includes support for gRPC to enable high-performance remote procedure calls.

1. Start the gRPC Server: Run the following command:

   node grpcServer.js

2. Use the gRPC Client: Execute the client to interact with the server:

   node grpcClient.js

3. Proto File: The .proto file for defining gRPC services and messages is located in the protos directory.

That's it! Your gRPC server and client should now be operational. 🚀

The Budget Management API can be run in a Docker container for easy deployment and scaling.

You can build and run the app using Docker Compose:

docker-compose up --build

The Budget Management API now supports advanced deployment strategies for production-grade deployments:

1. Blue-Green Deployment: Zero-downtime deployments with instant rollback capability
2. Canary Deployment: Gradual traffic shifting for risk mitigation
3. Rolling Deployment: Standard Kubernetes rolling updates

# Deploy blue and green environments
kubectl apply -f kubernetes/backend-deployment-blue.yaml
kubectl apply -f kubernetes/backend-deployment-green.yaml
kubectl apply -f kubernetes/frontend-deployment-blue.yaml
kubectl apply -f kubernetes/frontend-deployment-green.yaml

# Deploy services
kubectl apply -f kubernetes/backend-service-blue-green.yaml
kubectl apply -f kubernetes/frontend-service-blue-green.yaml

# Apply production-ready configurations
kubectl apply -f kubernetes/hpa.yaml
kubectl apply -f kubernetes/pdb.yaml
kubectl apply -f kubernetes/network-policy.yaml
kubectl apply -f kubernetes/ingress.yaml
kubectl apply -f kubernetes/servicemonitor.yaml

# Switch traffic (after validation)
kubectl patch service backend-service -p '{"spec":{"selector":{"version":"green"}}}'

# Deploy stable version (90% traffic)
kubectl apply -f kubernetes/backend-deployment-canary-stable.yaml
kubectl apply -f kubernetes/frontend-deployment-canary-stable.yaml

# Deploy canary version (10% traffic)
kubectl apply -f kubernetes/backend-deployment-canary.yaml
kubectl apply -f kubernetes/frontend-deployment-canary.yaml

# Deploy services
kubectl apply -f kubernetes/backend-service-canary.yaml
kubectl apply -f kubernetes/frontend-service-canary.yaml

# Apply production-ready configurations
kubectl apply -f kubernetes/hpa.yaml
kubectl apply -f kubernetes/pdb.yaml
kubectl apply -f kubernetes/network-policy.yaml

• Health Checks: Liveness, readiness, and startup probes
• Auto-scaling: Horizontal Pod Autoscaler (HPA) based on CPU/Memory
• High Availability: Pod anti-affinity and disruption budgets
• Security: Network policies, non-root containers, dropped capabilities
• Monitoring: Prometheus ServiceMonitor integration
• Resource Management: CPU/Memory requests and limits
• Ingress: SSL/TLS termination, rate limiting, timeouts

For detailed deployment procedures and best practices, see:

• Deployment Guide - Comprehensive deployment strategies
• Kubernetes Overview - Architecture and components
• Quick Start Guide - Step-by-step deployment

Access metrics at:

• Backend: http://backend-service:3000/metrics
• Frontend: http://frontend-service:3001/metrics

View health endpoints:

• Backend Health: http://backend-service:3000/health
• Backend Readiness: http://backend-service:3000/ready

There is also a Spring Boot Java version of the Budget Management API available in the spring-boot directory. It is built using Maven and Gradle.

To run the Spring Boot Maven application, follow these steps:

1. Navigate to the spring-boot directory:

   cd spring

2. Build the application using Maven:

    mvn clean install

3. Run the application:

   mvn spring-boot:run

4. Access the Spring Boot application at http://localhost:8080.

To run the Spring Boot Gradle application, follow these steps:

1. Navigate to the spring-boot directory:

   cd gradle

2. Build the application using Gradle:

    ./gradlew build

3. Run the application:

   ./gradlew bootRun

4. Access the Spring Boot application at http://localhost:8080.

There is also a Dotnet C# version of the Budget Management API available in the dotnet directory. It is built using ASP.NET Core.

To run the Dotnet C# application, follow these steps:

1. Navigate to the dotnet directory:

   cd dotnet

2. Build the application using the .NET CLI:

    dotnet build

3. Run the application:

   dotnet run

4. Access the Dotnet C# application at http://localhost:5000.

The Budget Management API includes an advanced Jenkins pipeline with support for multiple deployment strategies and production-ready features.

1. Multiple Deployment Strategies:

   • Rolling: Standard rolling updates with zero-downtime
   • Blue-Green: Instant traffic switching with zero-downtime
   • Canary: Gradual traffic shifting with configurable percentage

2. Comprehensive Testing:

   • Unit tests with coverage reporting
   • Integration tests
   • Smoke tests post-deployment
   • Performance tests
   • Security audits

3. Code Quality Checks:

   • ESLint for code linting
   • npm audit for security vulnerabilities
   • Dependency checking for outdated packages

4. Docker Integration:

   • Automated Docker image building
   • Multi-stage builds for optimization
   • Push to Docker registry with versioning
   • Image tagging based on Git commit SHA

5. Kubernetes Deployment:

   • Automated deployment to Kubernetes clusters
   • Health checks and validation
   • Automatic rollback on failure
   • Traffic switching for blue-green deployments
   • Canary analysis and promotion

6. Monitoring and Notifications:

   • Slack notifications for build status
   • Deployment success/failure alerts
   • Real-time progress updates
   • Git tag creation for successful deployments

Configure the pipeline with these parameters:

• DEPLOYMENT_STRATEGY: Choose from rolling, blue-green, or canary
• ENVIRONMENT: Select staging or production
• CANARY_PERCENTAGE: Set traffic percentage for canary deployments (1-100)
• RUN_SMOKE_TESTS: Enable/disable smoke tests after deployment
• AUTO_ROLLBACK: Enable automatic rollback on deployment failure

1. Checkout: Clone repository and extract commit information
2. Environment Setup: Configure Node.js environment
3. Install Dependencies: Install npm packages for backend and frontend
4. Code Quality & Security Checks: Run linting, security audit, and dependency checks in parallel
5. Run Tests: Execute unit and integration tests in parallel
6. Build: Build backend and frontend applications in parallel
7. Build Docker Images: Create and push Docker images to registry
8. Deploy: Execute chosen deployment strategy (rolling, blue-green, or canary)
9. Smoke Tests: Validate deployment with smoke tests
10. Health Check: Verify application health with automatic rollback on failure
11. Performance Tests: Run performance validation

DEPLOYMENT_STRATEGY: blue-green
ENVIRONMENT: production
RUN_SMOKE_TESTS: true
AUTO_ROLLBACK: true

DEPLOYMENT_STRATEGY: canary
ENVIRONMENT: production
CANARY_PERCENTAGE: 10
RUN_SMOKE_TESTS: true
AUTO_ROLLBACK: true

DEPLOYMENT_STRATEGY: rolling
ENVIRONMENT: staging
RUN_SMOKE_TESTS: true
AUTO_ROLLBACK: true

1. Configure Credentials in Jenkins:

   • docker-registry-credentials: Docker registry username/password
   • kubeconfig-credentials: Kubernetes configuration file
   • slack-webhook: Slack webhook URL for notifications

2. Create Pipeline Job:

   • New Item → Pipeline
   • Configure parameters as described above
   • Pipeline script from SCM: Point to repository Jenkinsfile

3. Configure Webhooks:

   • Add GitHub/GitLab webhook to trigger builds on push
   • Webhook URL: http://jenkins-server/github-webhook/

• Automatic Rollback: Triggers on health check failures or test failures
• Git Tagging: Successful deployments are tagged with deploy-{commit-sha}
• Parallel Execution: Tests and builds run in parallel for faster execution
• Coverage Reports: HTML coverage reports published after tests
• Artifact Archiving: Test results archived for historical tracking
• Clean Workspace: Automatic cleanup after pipeline completion

The Jenkinsfile includes sophisticated deployment functions:

• deployRolling(): Executes rolling deployment strategy
• deployBlueGreen(): Manages blue-green deployment with traffic switching
• deployCanary(): Handles canary deployment with gradual rollout
• validateDeployment(): Validates new deployment health
• validateCanaryHealth(): Checks canary deployment health
• performRollback(): Automatic rollback to previous version
• sendNotification(): Sends Slack notifications for pipeline events

For detailed deployment procedures, see Deployment Guide.

The Budget Management API also includes a GitHub Actions workflow for continuous integration and deployment.

1. Workflow Configuration: The .github/workflows/ci.yml file defines the CI/CD workflow, including steps for checking out code, installing dependencies, running tests, and building the application.
2. Job Setup: The workflow is triggered on push and pull request events to the main branch.
3. Automated Testing: The workflow runs npm test to ensure all tests pass before proceeding to the build or deployment stages.
4. Deployment: The workflow can be configured to deploy the application to Render or other hosting services using GitHub Actions deployment steps.
5. Environment Variables: Use GitHub Secrets to securely manage sensitive information like API keys and database credentials.
6. Notifications: Configure GitHub Actions to send notifications to Slack or email on build and deployment statuses.

This setup allows for automated testing and deployment, ensuring that the application is always in a deployable state.

The Budget Management API includes unit tests for all endpoints and services.

To run the tests, use the following command:

npm test

The test results will be displayed in the console.

Watch Mode: To run tests in watch mode, which automatically re-runs tests on file changes, use:

npm test:watch

Coverage Report: To generate a code coverage report, use:

npm test:coverage

Mocha and Chai tests: In addition to the Jest tests, the project also includes Mocha and Chai tests for the application. These tests can be run using:

npm run test:mocha

Contributions are welcome! Please fork the repository, create a feature branch, and submit a pull request:

1. Fork the repository.
2. Create a new branch (git checkout -b feature-branch).
3. Make changes and commit them (git commit -am 'Add new feature').
4. Push to the branch (git push origin feature-branch).
5. Create a new pull request. We will review your changes and merge them if they look good.

This project is built with ❤️ by:

• Son Nguyen - hoangsonww

For more information about me, you can visit my personal website or connect with me on LinkedIn:

• Website: https://sonnguyenhoang.com
• Email: hoangson091104@gmail.com
• LinkedIn: https://www.linkedin.com/in/hoangsonw
• GitHub: @hoangsonww

Feel free to reach out if you have any questions or feedback! 🚀

Thank you for using the Budget Management API. For questions, feedback, or support, please open an issue or contact me directly.

Created with ❤️ by Son Nguyen in 2024. All rights reserved.

⬆️ Back to Top