GRAPHQL–BASED DEVOPS APPLICATION

BUILT WITH NODE.JS & EXPRESS, POWERED BY MONGODB

      

DOCKERIZED, NGINX INGRESS, K8S-ORCHESTRATED, AUTOMATED WITH GITHUB ACTIONS & ARGOCD

               

MONITORED WITH PROMETHEUS & GRAFANA

 

---

This system exposes a GraphQL API for managing Clients and Products, backed by MongoDB and instrumented with Prometheus metrics. It leverages Docker, Kubernetes, NGINX Ingress, GitHub Actions, ArgoCD GitOps, and production-grade monitoring with Prometheus and Grafana. The project demonstrates a complete DevOps pipeline with automated deployments, container orchestration, and modern API design, built with reliability and long-term engineering practices in mind.

📑 Table of Contents

• 🔥 Features
• 📁 Project Structure
• 📌 Technology Stack Overview
• ⚙ Setup & Installation
• 📡 How to Test GraphQL APIs
• 🐳 Docker Setup (Optional)
• ☸️ Kubernetes Deployment with NGINX (Optional)
• 🌀 GitOps with Argo CD (Optional)
• 🤖 GitHub Actions & Automated Docker Builds (Optional)
• 📈 Monitoring with Prometheus & Grafana (Optional)
• 👤 Created By
• 📝 License

---

🔥 Features

📡 GraphQL API Features:

Feature	Description
CRUD for Clients	Create, read, update, and delete client records with full validation and error handling.
CRUD for Products	Manage products linked to clients, with validation to ensure data consistency and integrity.
Field Validation	Ensures correct email format, non-empty names, positive prices, and other field constraints.
Nested References	Products are linked to clients, allowing relational queries and efficient data retrieval.
GraphiQL UI	Interactive interface to test queries and mutations, with real-time feedback for developers.

---

☸️ DevOps & Deployment Features:

Feature	Description
Dockerized Services	Both API and MongoDB are containerized for consistent environments, portability, and easy deployment.
Kubernetes Deployment & Service	Provides automated scaling, load balancing, service discovery, and high availability for the system.
TLS-Secured Ingress	Routes traffic via NGINX Ingress with HTTPS, supporting self-signed or custom TLS certificates.
GitHub Actions CI	Continuous Integration workflow automates Docker image build, testing, and pushing on code changes.
ArgoCD GitOps	Automatically syncs and deploys Kubernetes manifests from Git, enabling GitOps-based deployments.

---

📊 Monitoring Features:

Feature	Description
Prometheus Metrics	Exposes a /metrics endpoint for monitoring API performance, request counts, and system health.
Grafana Dashboards	Visualizes metrics with customizable dashboards, alerting, and historical trend analysis.
Helm Installation	Prometheus and Grafana installed and configured via Helm charts, simplifying deployment and upgrades.

---

📁 Project Structure

The following structure is used for this project:

graphql-system-k8s-nginx-prometheus-grafana/
│
├── .github/                          # GitHub Actions workflows for building Docker images       
│   └── workflows/
│       └── build-docker-image.yaml
│
├── argocd/                           # ArgoCD GitOps application configuration
│   └── application.yaml
│
├── k8s/                              # Kubernetes resource manifests
│   ├── graphql-deployment.yaml
│   ├── graphql-ingress-https.yaml    # Official NGINX Ingress controller configuration
│   ├── graphql-service.yaml
│   ├── mongo-deployment.yaml
│   └── mongo-service.yaml
│
├── nginx/                            # Custom NGINX config for local/testing environments
│   ├── default.conf
│   ├── nginx-config.yaml
│   ├── nginx-deployment.yaml
│   └── nginx-service.yaml
│
├── node_modules/                   
│
├── src/                               # GraphQL API source code
│   ├── config/
│   │   └── db.js
│   ├── graphql/                       # GraphQL schema, types, models, queries, and mutations
│   │   ├── models/
│   │   │   ├── Client.js
│   │   │   └── Product.js
│   │   ├── mutations/
│   │   │   ├── ClientMutations.js
│   │   │   └── ProductMutations.js
│   │   ├── queries/
│   │   │   ├── ClientQueries.js
│   │   │   └── ProductQueries.js
│   │   ├── schema/
│   │   │   └── schema.js
│   │   └── types/
│   │       ├── ClientType.js
│   │       ├── MessageType.js
│   │       └── ProductType.js
│   ├── main/
│   │   └── app.js
│   ├── monitoring/                    # Prometheus metrics export
│   │   ├── metrics.js
│   │   └── prometheus&grafana.txt     # Notes and configuration references for monitoring setup
│   └── seed/
│       └── seed.js
│
├── .dockerignore
├── .gitignore
├── Dockerfile
├── docker-compose.yml                 # Local multi-service setup
├── LICENSE
├── README.md
├── server.js
└── package.json                       # Dependencies & scripts

---

📌 Technology Stack Overview

The following technologies are used in this project:

Layer	Technology	Description
API Backend	Node.js, Express, express-graphql, GraphQL	Handles all API requests and exposes GraphQL endpoints
Database	MongoDB, Mongoose	Stores client and product data with schema modeling
Containerization	Docker, docker-compose	Packages application services for portable deployment
Orchestration	Kubernetes	Manages, scales, and runs containers in clusters
Ingress Controller	NGINX Ingress	Routes external traffic into the cluster with TLS
DevOps Workflow	GitHub Actions	Automates Docker image build and CI pipeline
GitOps Automation	ArgoCD	Syncs deployments to cluster using GitOps flow
Monitoring	Prom-client, Prometheus, Grafana (Helm)	Collects metrics and visualizes system performance

---

⚙ Setup & Installation

Follow these steps to run the project locally using Docker:

1. ✅ Clone the Repository

git clone https://github.com/PAIshanMadusha/graphql-system-k8s-nginx-prometheus-grafana.git

2. ✅ Navigate to the Project Directory

cd graphql-system-k8s-nginx-prometheus-grafana

3. ▶️ Run the Docker Compose File

This project can run locally with Docker. Make sure you have Docker Desktop (or Docker Engine) running on your system.

docker-compose up --build

4. ⚡ Successful Startup Output

If everything is configured correctly, check each container's logs in Docker Desktop or your terminal. You should see output similar to:

MongoDB Connected Successfully!
Server is running on port: 4000
Docker or Kubernetes Pod Name: {docker-hostname}

🌐 Test the App: Visit: http://localhost:4000

---

📡 How to Test GraphQL APIs

You can test the APIs by navigating to http://localhost:4000/graphql, which will open the GraphiQL UI. From there, you can test the queries and mutations shown below.

1. ✅ Mutation to add a new client:

mutation{
  addClient(name: "test", email: "test@test.com", phone: "0000000000", address: "test"){
    message
    client{
      id
      name
      email
      phone
      address
    }
  }
}

2. ✅ Mutation to add a new product:

mutation{
  addProduct(name: "test", brand: "test", description: "test", price: 10.10, clientId: "real-client-id"){
    message,
    product{
      id
      name
      brand
      description
      price
      client{
        id
        name
        email
        phone
        address
      }
    }
  }
}

3. ✅ Query to get all clients:

{
  clients{
    id
    name
    email
    phone
    address
  }
}

4. ✅ Query to get all products:

{
  products{
    id
    name
    brand
    description
    price
    client{
      id
      name
      email
      phone
      address
    }
  }
}

5. ✅ Query to get a single client by ID:

{
  client(id: "real-client-id"){
    id
    name
    email
    phone
    address
  }
}

6. ✅ Query to get a single product by ID:

{
  product(id: "real-product-id"){
    id
    name
    brand
    description
    price
    client{
      id
      name
     	email
      phone
      address
    }
  }
}

7. ✅ Mutation to update an existing client:

mutation{
  updateClient(id: "real-client-id", name: "test2", email: "test2@test.com", phone: "1111111111", address: "test2"){
    message
    client{
      id
      name
      email
      phone
      address
    }
  }
}

8. ✅ Mutation to update an existing product:

mutation{
  updateProduct(id: "real-product-id", name: "test2", brand: "test2", description: "test2", price: 20.20){
    message
    product{
      id
      name
      brand
      description
      price
      client{
        id
        name
        email
        phone
        address
      }
    }
  }
}

9. ✅ Mutation to delete a client:

mutation{
  deleteClient(id: "real-client-id"){
    message
    client{
      id
      name
      email
      phone
      address
    }
  }
}

10. ✅ Mutation to delete a product:

mutation{
  deleteProduct(id: "real-product-id"){
    message
    product{
      id
      name
      brand
      description
      price
    }
  }
}

---

🐳 Docker Setup (Optional)

These steps allow you to build your own Docker image or pull the pre-built image for testing with Kubernetes and Argo CD.

Official Docker Image: ishanmadusha/graphql-system-k8s-nginx-prometheus-grafana:latest

📥 Pull the latest image (optional)

docker pull ishanmadusha/graphql-system-k8s-nginx-prometheus-grafana:latest

1. ✅ Build Your Own Docker Image

If you want to build a custom image, update the image name inside: graphql-system-k8s-nginx-prometheus-grafana/k8s/graphql-deployment.yaml

docker build -t <your-username>/graphql-system-k8s-nginx-prometheus-grafana:latest .

2. ✅ Push Your Image to Docker Hub

docker push <your-username>/graphql-system-k8s-nginx-prometheus-grafana:latest

---

☸️ Kubernetes Deployment with NGINX (Optional)

Make sure Minikube or a Kubernetes cluster is running before deployment: 👉 https://minikube.sigs.k8s.io/docs

🔍 Components in k8s/

File	Description
graphql-deployment.yaml	Main GraphQL application Deployment (4 replicas for HA + load balancing)
graphql-service.yaml	ClusterIP Service exposing the GraphQL app internally on port 4000
graphql-ingress-https.yaml	NGINX Ingress with HTTPS (self-signed cert supported via TLS Secret)
mongo-deployment.yaml	MongoDB Deployment (single pod, uses emptyDir for ephemeral storage)
mongo-service.yaml	Internal ClusterIP Service for MongoDB at mongo-service:27017

🔍 Components in nginx/ (Testing Only — Not Used in Production)

File	Description
default.conf	Raw NGINX config for local or standalone container routing
nginx-config.yaml	Converts the config into ConfigMap for Kubernetes use
nginx-deployment.yaml	Test NGINX Deployment referencing ConfigMap
nginx-service.yaml	ClusterIP service for NGINX test instance

⚠️ This directory is for testing only.

Production routing is handled by the official Ingress-NGINX controller, configured in graphql-ingress-https.yaml.

1. ✅ Generate a self-signed certificate (OpenSSL):

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout localhost.key -out localhost.crt -subj "/CN=localhost/O=localhost"

2. ✅ Create a TLS secret in Kubernetes:

kubectl create secret tls localhost-tls --key localhost.key --cert localhost.crt

3. ✅ Deploy All Resources:

kubectl apply -f k8s/

4. ✅ Access the Application via HTTPS Ingress or port-forward alternative:

https://localhost/graphql

kubectl port-forward svc/graphql-system-k8s-nginx-prometheus-grafana 4000:4000

🌐 Test the App: Visit: http://localhost:4000

---

🌀 GitOps with Argo CD (Optional)

Install Argo CD on Minikube and configure it to automate Kubernetes deployments, Learn more: https://argo-cd.readthedocs.io/en/stable

1. ✅ Apply the Argo CD Application Configuration:

The file argocd/application.yaml is responsible for automatically syncing Kubernetes with your GitHub repository, Apply the config:

kubectl apply -f argocd/application.yaml -n argocd

Make sure you update your GitHub repository URL inside the file: graphql-system-k8s-nginx-prometheus-grafana/argocd/application.yaml

🗺️ After applying, Argo CD will:

* Track your GitHub repository as the source of truth

* Identify any updates to YAML manifests or image tags

* Fetch the newest Docker images built by GitHub Actions

* Apply all changes to the Kubernetes cluster without manual steps

2. ✅ Access the ArgoCD UI via port forwarding (more info in application.yaml):

kubectl port-forward svc/argocd-server -n argocd 8080:443

🌐 View the ArgoCD UI: Visit https://localhost:8080

---

The view of how Argo CD automation works with this application

---

🤖 GitHub Actions & Automated Docker Builds (Optional)

A CI/CD pipeline is included at .github/workflows/build-docker-image.yaml, which automatically builds and pushes the Docker image whenever changes are committed to the main branch.

🔄 How the Pipeline Works

* The repository is checked out for the latest changes.

* GitHub Actions authenticates with Docker Hub via secure GitHub Secrets.

* A new Docker image is built from the updated source code.

* The freshly built image is pushed to Docker Hub with the latest tag.

🔁 What This Achieves

* Eliminates the need for manual image builds or pushes.

* Ensures every commit to main produces a new container image.

* Argo CD continuously syncs the cluster, deploying changes automatically.

* Provides a fully automated and reliable CI/CD + GitOps workflow.

---

📈 Monitoring with Prometheus & Grafana (Optional)

1. 🌐 You can view application metrics by navigating to http://localhost:4000/metrics, which exposes all Prometheus-compatible metrics of the application.

2. ⚡ To set up Prometheus and Grafana on Kubernetes (Windows recommended via Helm), follow the guide provided in: src/monitoring/prometheus&grafana.txt, This file includes all required configurations and setup steps clearly.

---

Prometheus dashboard view live metrics collected while the application is running

---

Grafana dashboard visual representation of application metrics

---

👤 Created By

Ishan Madhusha
GitHub: PAIshanMadusha

Feel free to explore my work and reach out if you'd like to collaborate! 🚀

---

📝 License

This project is licensed under the MIT License.
See the LICENSE file for more details.