diff --git a/README.md b/README.md index e733c6f..b51fd31 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,30 @@ -FullStack DevSecOps Demo - -A production-grade fullstack pipeline showcasing modern DevSecOps practices β€” from secure CI/CD, to observability, to Infrastructure-as-Code (IaC). +# πŸš€ FullStack DevSecOps Demo +A production-grade fullstack pipeline showcasing modern DevSecOps practices β€” from secure CI/CD to observability and Infrastructure-as-Code (IaC). This project demonstrates how to take a simple Node.js/Express app and wrap it with a battle-tested DevSecOps workflow used in real companies. -🌟 Highlights - - -CI/CD Pipeline: GitHub Actions with linting, testing, dependency audits, Docker builds, Trivy scans, Gitleaks, CodeQL, Checkov & Terrascan. - - -Secure Containerization: Hardened Dockerfiles with non-root users and HEALTHCHECK instructions. - - -Runtime Security: Gitleaks (secret scanning), CodeQL (static analysis), npm audit (dependency vulnerabilities). - - -Observability Stack: - -Prometheus for metrics collection - -Grafana dashboards (CPU %, memory, HTTP request rates, error rate, latency) - -Alertmanager + Slack for real-time alerts - -Sentry for application-level error monitoring and release tracking - +--- -Environments: +## 🌟 Highlights -Staging: auto-deploy on develop +- **CI/CD Pipeline**: GitHub Actions with linting, testing, dependency audits, Docker builds, Trivy scans, Gitleaks, CodeQL, Checkov & Terrascan +- **Secure Containerization**: Hardened Dockerfiles with non-root users and HEALTHCHECK instructions +- **Runtime Security**: Gitleaks (secret scanning), CodeQL (static analysis), npm audit (dependency vulnerabilities) +- **Observability Stack**: + - Prometheus for metrics collection + - Grafana dashboards (CPU %, memory, HTTP request rates, error rate, latency) + - Alertmanager + Slack for real-time alerts + - Sentry for application-level error monitoring and release tracking +- **Environments**: + - Staging: auto-deploy on `develop` + - Production: auto-deploy on `main` +- **IaC Versioning**: Full `render.yaml` and Helm manifests for portability to Kubernetes (k3s, GKE, EKS) -Production: auto-deploy on main +--- +## πŸ—οΈ Architecture -IaC Versioning: Full render.yaml and Helm manifests for portability to Kubernetes (k3s, GKE, EKS). - -πŸ—οΈ Architecture - -``` +```mermaid flowchart TD A[GitHub Push] -->|GitHub Actions| B[CI/CD Pipeline] B -->|Docker Build + Scan| C[Docker Hub] @@ -48,179 +34,171 @@ flowchart TD F --> G[Grafana Dashboards] F --> H[Alertmanager -> Slack] E -->|Errors| I[Sentry] - ``` -πŸ”„ CI/CD Workflow - -Key stages from .github/workflows/cicd.yml: - -Lint & Test - -ESLint for code quality - -Jest for unit tests - -Security Scans - -npm audit - -Trivy (container vulnerabilities) - -Gitleaks (secrets) - -CodeQL (static analysis) +# πŸ”„ CI/CD Workflow -Checkov + Terrascan (IaC security) +## βœ… Lint & Test +- **ESLint** β†’ code quality +- **Jest** β†’ unit tests -Build & Push +## πŸ”’ Security Scans +- **npm audit** - dependency vulnerabilities +- **Trivy** - container vulnerabilities +- **Gitleaks** - secrets detection +- **CodeQL** - static analysis +- **Checkov + Terrascan** - IaC security -Docker image pushed to Docker Hub with commit + latest tags +## 🐳 Build & Push +- Docker image pushed to Docker Hub with commit + latest tags -Deploy +## πŸš€ Deployments -Render Staging (branch: develop) +### Staging (`develop` branch) +πŸ”— **Live Staging App**: [Your Staging URL Here] -Render Prod (branch: main) +### Production (`main` branch) +πŸ”— **Live Production App**: [Your Production URL Here] -Automatic Sentry release tracking +## πŸ”” Notifications +Slack messages for staging/prod deployments with build status: -Notify -Slack messages for staging/prod deployments with build status +--- +# πŸ“Š Observability -πŸ“Š Observability +## Prometheus +- Scrapes app `/metrics` endpoint (via `prom-client`) +- Collects: + - Default Node.js process metrics + - `http_requests_total` counter + - Latency histogram -Prometheus +πŸ”— **See live link here**: [Your Prometheus URL Here] -Scrapes app /metrics endpoint (via prom-client). +## Grafana Dashboards +Includes panels for: +- CPU % +- Memory usage +- HTTP requests/sec +- 5xx error rate +- 95th percentile latency -Collects: +πŸ”— **See live link here**: [Your Grafana URL Here] -Default Node.js process metrics -http_requests_total counter +## Alertmanager +- Sends alerts to Slack via webhook +- Starter rules: + - CPU > 80% for 2 minutes + - Error rate > 5% over 5 minutes -Latency histogram +## Sentry +- Captures unhandled exceptions +- Tied to GitHub Actions release versions +- Shows "Deployed to Staging/Prod" in release timeline +--- -Grafana -Preprovisioned dashboards: +## πŸ“Έ Project in Action -CPU % +### βœ… Lint & Tests Passing +![Lint + Tests](docs/images/Lint-test.png) -Memory usage +### πŸš€ Render Staging Deployment +![Render Staging Deploy](docs/images/Render-staging.png) -HTTP requests/sec +πŸ”— [Staging App URL](docs/images/Staging-Url.png) -5xx error rate +### 🌍 Production Deployment +![Production URL](docs/images/Prod-url.png) -95th percentile latency +### πŸ”” Slack Notifications +![Slack Notifications](docs/images/SLACK-NOTIFY.png) +### πŸ“Š Observability with Prometheus & Grafana +![Prometheus Dashboard](docs/images/Prometheus-dashh.png) -Alertmanager -Sends alerts to Slack via webhook. -Starter rules: - -CPU > 80% for 2 minutes - -Error rate > 5% over 5 minutes - - -Sentry - -Captures unhandled exceptions. - -Tied to GitHub Actions release versions. - -Shows β€œDeployed to Staging/Prod” in release timeline. - - -🐳 Docker Hardening +# 🐳 Docker Hardening All service images include: +- `HEALTHCHECK` instructions +- Non-root user execution +- Minimal base images (`node:18-alpine`, `alpine:3.20`, etc.) -HEALTHCHECK instructions - -Non-root user execution - -Minimal base images (node:18-alpine, alpine:3.20, etc.) - - -☸️ Kubernetes (Future-Ready) - -Helm charts included for: +--- -myapp (Node.js/Express) +# ☸️ Kubernetes (Future-Ready) -Prometheus +## Helm charts included for: +- `myapp` (Node.js/Express) +- Prometheus +- Grafana +- Alertmanager -Grafana +## Secrets Management +Secrets managed via K8s Secret resources (Slack webhook, Grafana admin password). -Alertmanager +## Supported Deployment Environments +- **Local dev**: k3s / kind +- **Cloud**: GKE, EKS, AKS -Supports secrets via K8s Secret resources (e.g. Slack webhook, Grafana admin password). +--- -Designed for deployment on: +# ⚑ Quick Start (Render) -Local dev: k3s / kind +1. **Fork this repo** +2. **Set GitHub Actions secrets**: + - `DOCKERHUB_USERNAME`, `DOCKERHUB_TOKEN` + - `RENDER_API_KEY`, `RENDER_SERVICE_ID`, `RENDER_SERVICE_ID_PROD` + - `SENTRY_AUTH_TOKEN`, `SENTRY_ORG`, `SENTRY_PROJECT` + - `SLACK_WEBHOOK_URL` +3. **Push to `develop`** β†’ staging deploy +4. **Merge to `main`** β†’ production deploy -Cloud: GKE, EKS, AKS +--- -⚑ Quick Start (Render) -Fork this repo - -Set secrets in GitHub Actions: - -DOCKERHUB_USERNAME / DOCKERHUB_TOKEN - -RENDER_API_KEY, RENDER_SERVICE_ID, RENDER_SERVICE_ID_PROD - -SENTRY_AUTH_TOKEN, SENTRY_ORG, SENTRY_PROJECT - -SLACK_WEBHOOK_URL - -Push to develop β†’ staging deploy - -Merge to main β†’ production deploy - -πŸ“‚ Repo Structure +πŸ“‚ Repository Structure ``` -. -β”œβ”€β”€ src/ # Node.js app (Express + Sentry + Prometheus metrics) -β”œβ”€β”€ infra/ # Infra services + +β”œβ”€β”€ src/ # Node.js app (Express + Sentry + Prometheus metrics) +β”œβ”€β”€ infra/ # Infra services β”‚ β”œβ”€β”€ prometheus/ β”‚ β”œβ”€β”€ grafana/ β”‚ └── alertmanager/ -β”œβ”€β”€ helm/ # Helm charts for k8s migration -β”œβ”€β”€ .github/workflows/ # CI/CD pipelines -β”œβ”€β”€ render.yaml # Render IaC config -└── Dockerfile # App Dockerfile - +β”œβ”€β”€ helm/ # Helm charts for k8s migration +β”œβ”€β”€ .github/workflows/ # CI/CD pipelines +β”œβ”€β”€ render.yaml # Render IaC config +└── Dockerfile # App Dockerfile ``` -Why This Matters +🎯 Why This Matters -βœ… Full DevSecOps pipeline: not just CI/CD, but integrated security, monitoring, and alerting. +| Feature | Benefit | +| ----------------------- | --------------------------------------------------------- | +| Full DevSecOps pipeline | Integrated security, monitoring, and alerting | +| Cloud-native ready | Helm charts β†’ easy migration to Kubernetes | +| Production realism | Error tracking, observability, secrets mgmt, IaC scanning | +| Team collaboration | Slack notifications + Sentry releases β†’ transparency | +| Hands-on expertise | End-to-end modern DevSecOps toolchain experience | -βœ… Cloud-native ready: Helm charts β†’ easy migration to Kubernetes. -βœ… Production realism: covers error tracking, observability, secrets management, IaC scanning. -βœ… Team collaboration: Slack notifications + Sentry releases β†’ transparent deployments. - -βœ… Hands-on expertise across Node.js, Docker, GitHub Actions, Sentry, Prometheus, Grafana, Alertmanager, Checkov, Terrascan, Render, Helm. +πŸ“¬ Contact +Interested in how I can bring end-to-end DevSecOps expertise to your team? Let’s connect! -This repo is my portfolio centerpiece: a showcase of how I’d run secure, observable, cloud-ready software delivery in a real engineering org. +
+**Built with ❀️ to demonstrate modern DevSecOps practices** -πŸ“¬ Contact +[![GitHub stars](https://img.shields.io/github/stars/wizzfi1/fullstack-devsecops-demo?style=social)](https://github.com/wizzfi1/fullstack-devsecops-demo) +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) -If you’re interested in how I can bring end-to-end DevSecOps expertise to your team. \ No newline at end of file +