Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/solomonkassa/nginx-automation

🚀 NGINX Automation Framework A comprehensive, enterprise-grade NGINX automation framework designed for high-availability, security-focused, and scalable web infrastructure deployment.
https://github.com/solomonkassa/nginx-automation

ansible ci-cd doker kubernetes nginx nginx-docker prometheus script security shell-script

Last synced: 2 months ago
JSON representation

🚀 NGINX Automation Framework A comprehensive, enterprise-grade NGINX automation framework designed for high-availability, security-focused, and scalable web infrastructure deployment.

Awesome Lists containing this project

README 

          
# 🚀 NGINX Automation Framework



A comprehensive, enterprise-grade NGINX automation framework designed for high-availability, security-focused, and scalable web infrastructure deployment.



[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

[![GitHub Release](https://img.shields.io/github/v/release/your-org/nginx-automation)](https://github.com/Solomonkassa/nginx-automation/releases)

[![Build Status](https://img.shields.io/jenkins/build?jobUrl=https%3A%2F%2Fjenkins.example.com%2Fjob%2Fnginx-automation)](https://jenkins.example.com/job/nginx-automation)

[![Security Scan](https://img.shields.io/badge/security-scan-brightgreen)](SECURITY.md)

[![Documentation](https://img.shields.io/badge/docs-comprehensive-blue)](https://docs.example.com/nginx-automation)



## 📋 Table of Contents



- [Overview](#overview)

- [Key Features](#key-features)

- [Architecture](#architecture)

- [Quick Start](#quick-start)

- [Installation](#installation)

- [Configuration](#configuration)

- [Deployment](#deployment)

- [Monitoring](#monitoring)

- [Security](#security)

- [CI/CD Integration](#cicd-integration)

- [Disaster Recovery](#disaster-recovery)

- [Contributing](#contributing)

- [License](#license)

- [Support](#support)



## 🌟 Overview



This framework provides a complete, production-ready solution for automating NGINX deployment and management across various environments. It incorporates industry best practices for security, performance, and reliability.



**Purpose**: Streamline NGINX infrastructure provisioning, configuration management, certificate automation, monitoring, and disaster recovery processes.



**Target Environments**: Production, Staging, Development, and Disaster Recovery sites.



## 🚀 Key Features



### 🔒 **Security**

- Automatic SSL/TLS certificate management (Let's Encrypt)

- WAF (Web Application Firewall) integration with OWASP Core Rule Set

- Security headers enforcement (CSP, HSTS, X-Frame-Options)

- Rate limiting and DDoS protection

- Regular security scanning and vulnerability assessment



### ⚡ **Performance**

- Optimized caching strategies

- HTTP/2 and HTTP/3 support

- Gzip/Brotli compression

- Load balancing with health checks

- Connection pooling and keep-alive optimization



### 🔄 **Automation**

- Infrastructure as Code (Terraform)

- Configuration Management (Ansible)

- Container Orchestration (Kubernetes/Docker)

- Automated certificate renewal

- Zero-downtime deployments



### 📊 **Monitoring & Observability**

- Real-time metrics with Prometheus

- Comprehensive dashboards with Grafana

- Structured JSON logging

- Distributed tracing support

- Alerting with multiple notification channels



### 🔧 **High Availability**

- Multi-zone/multi-region deployments

- Automated failover and recovery

- Blue-green deployment support

- Rolling updates with health checks

- Backup and restore automation



## 🏗 Architecture



### Infrastructure Diagram

```mermaid

graph TB

    A[Client Requests] --> B[Cloud Load Balancer]

    B --> C[NGINX Layer 1
Edge Proxies]

    C --> D[NGINX Layer 2
Application Proxies]

    D --> E[Backend Services]

    

    F[Monitoring] --> C

    F --> D

    F --> E

    

    G[CI/CD Pipeline] --> H[Configuration Repository]

    H --> I[Deployment Manager]

    I --> C

    I --> D

    

    J[Security Scanner] --> H

    K[Certificate Manager] --> C

    K --> D

```



### Directory Structure

```

nginx-automation/

├── terraform/              # Infrastructure as Code

│   ├── main.tf

│   ├── variables.tf

│   ├── outputs.tf

│   └── modules/

│       ├── network/

│       ├── compute/

│       └── security/

├── ansible/               # Configuration Management

│   ├── playbooks/

│   │   ├── deploy-nginx.yml

│   │   ├── security-harden.yml

│   │   └── cert-renew.yml

│   ├── roles/

│   │   ├── nginx/

│   │   ├── monitoring/

│   │   └── security/

│   └── inventories/

│       ├── production/

│       ├── staging/

│       └── development/

├── docker/                # Containerization

│   ├── Dockerfile

│   ├── docker-compose.yml

│   ├── docker-compose.prod.yml

│   └── entrypoint.sh

├── kubernetes/           # Kubernetes Manifests

│   ├── namespaces/

│   ├── deployments/

│   ├── services/

│   ├── configmaps/

│   ├── secrets/

│   └── helm/

│       └── nginx/

│           ├── Chart.yaml

│           ├── values.yaml

│           └── templates/

├── configs/              # NGINX Configurations

│   ├── nginx.conf

│   ├── conf.d/

│   │   ├── security.conf

│   │   ├── caching.conf

│   │   ├── compression.conf

│   │   └── logging.conf

│   ├── sites-available/

│   │   ├── app1.example.com.conf

│   │   └── app2.example.com.conf

│   └── templates/

│       ├── nginx.conf.j2

│       └── site.conf.j2

├── scripts/              # Automation Scripts

│   ├── deploy.sh

│   ├── health-check.sh

│   ├── cert-automation.sh

│   ├── backup.sh

│   ├── restore.sh

│   ├── security-scan.sh

│   └── performance-test.sh

├── monitoring/           # Monitoring Stack

│   ├── prometheus/

│   │   ├── prometheus.yml

│   │   ├── alert.rules

│   │   └── dashboard.yml

│   ├── grafana/

│   │   ├── dashboards/

│   │   │   ├── nginx-overview.json

│   │   │   ├── security.json

│   │   │   └── performance.json

│   │   └── datasources/

│   ├── loki/            # Log aggregation

│   └── tempo/           # Tracing

├── security/            # Security Configurations

│   ├── ssl/

│   │   ├── generate-certs.sh

│   │   └── renew-certs.sh

│   ├── waf-rules/

│   │   ├── modsecurity.conf

│   │   └── crs-setup.conf

│   └── policies/

│       ├── csp.json

│       └── rate-limiting.json

├── tests/               # Testing Suite

│   ├── unit/

│   │   └── nginx-test.bats

│   ├── integration/

│   │   └── api-test.sh

│   ├── load-test/

│   │   ├── k6-script.js

│   │   └── locustfile.py

│   ├── security-scan/

│   │   ├── zap-scan.yml

│   │   └── nmap-scan.sh

│   └── compliance/

│       ├── pci-dss.yml

│       └── gdpr.yml

├── ci-cd/               # CI/CD Pipelines

│   ├── Jenkinsfile

│   ├── .gitlab-ci.yml

│   ├── github-actions.yml

│   └── argo-cd/

│       ├── application.yaml

│       └── project.yaml

├── docs/                # Documentation

│   ├── architecture.md

│   ├── deployment-guide.md

│   ├── security-guide.md

│   ├── troubleshooting.md

│   └── api-reference.md

├── .github/             # GitHub Workflows

│   ├── workflows/

│   ├── ISSUE_TEMPLATE/

│   └── PULL_REQUEST_TEMPLATE/

└── environments/        # Environment Configs

    ├── production/

    ├── staging/

    └── development/

```



## 🚀 Quick Start



### Prerequisites



- Linux/Unix environment (Ubuntu 20.04+ recommended)

- Docker and Docker Compose

- Terraform v1.0+

- Ansible v2.10+

- kubectl and Helm v3+

- Git



### Quick Installation



```bash

# Clone the repository

git clone https://github.com/Solomonkassa/nginx-automation.git

cd nginx-automation



# Setup environment

cp .env.example .env

# Edit .env with your configuration



# Initialize infrastructure

make init



# Deploy development environment

make deploy-dev



# Verify deployment

make verify

```



### Docker Compose Quick Start



```bash

# Start the full stack with Docker Compose

docker-compose -f docker/docker-compose.full.yml up -d



# Check services

docker-compose ps



# View logs

docker-compose logs -f nginx

```



## 📦 Installation



### Detailed Installation Steps



1. **Clone and Setup**

   ```bash

   git clone --branch stable https://github.com/your-org/nginx-automation.git

   cd nginx-automation

   

   # Install dependencies

   ./scripts/setup.sh

   ```



2. **Configure Environment Variables**

   ```bash

   # Copy and edit environment configuration

   cp environments/development/.env.example environments/development/.env

   vi environments/development/.env

   ```



3. **Initialize Infrastructure**

   ```bash

   # Initialize Terraform

   cd terraform

   terraform init

   terraform plan -var-file="../environments/development/terraform.tfvars"

   terraform apply -var-file="../environments/development/terraform.tfvars"

   ```



4. **Configure Ansible**

   ```bash

   cd ../ansible

   cp inventories/development/hosts.example inventories/development/hosts

   vi inventories/development/hosts

   

   # Test connection

   ansible -i inventories/development/hosts all -m ping

   ```



## ⚙️ Configuration



### Core Configuration Files



#### Main NGINX Configuration (`configs/nginx.conf`)

```nginx

# Optimized for production

worker_processes auto;

worker_rlimit_nofile 100000;



events {

    worker_connections 4096;

    multi_accept on;

    use epoll;

}



http {

    include       /etc/nginx/mime.types;

    default_type  application/octet-stream;

    

    # Performance tuning

    sendfile on;

    tcp_nopush on;

    tcp_nodelay on;

    keepalive_timeout 65;

    keepalive_requests 1000;

    

    # Security includes

    include /etc/nginx/conf.d/security.conf;

    include /etc/nginx/conf.d/rate-limiting.conf;

    

    # Site configurations

    include /etc/nginx/sites-enabled/*;

}

```



#### Environment-Specific Configuration



Create environment-specific configuration in `environments//`:



```bash

environments/production/

├── .env                    # Environment variables

├── terraform.tfvars        # Terraform variables

├── ansible_vars.yml        # Ansible variables

├── kustomization.yaml      # Kubernetes customization

└── monitoring/             # Monitoring configs

```



### SSL/TLS Configuration



```bash

# Generate SSL certificates

./scripts/ssl/generate-certs.sh --domain example.com



# Configure automatic renewal

crontab -e

# Add: 0 3 * * * /opt/nginx-automation/scripts/ssl/renew-certs.sh

```



## 🚀 Deployment



### Deployment Strategies



#### 1. **Ansible Deployment**

```bash

# Deploy to production

ansible-playbook -i inventories/production/hosts \

    playbooks/deploy-nginx.yml \

    --extra-vars "@environments/production/ansible_vars.yml"

```



#### 2. **Kubernetes Deployment**

```bash

# Apply Kubernetes manifests

kubectl apply -k kubernetes/overlays/production/



# Verify deployment

kubectl get pods -n nginx-production

kubectl get svc -n nginx-production

```



#### 3. **Blue-Green Deployment**

```bash

# Deploy new version

./scripts/deploy-blue-green.sh --version 2.0.0



# Switch traffic

./scripts/switch-traffic.sh --to green



# Rollback if needed

./scripts/rollback.sh --to blue

```



### CI/CD Pipeline



The framework includes pre-configured pipelines for:



- **Jenkins**: `ci-cd/Jenkinsfile`

- **GitLab CI**: `ci-cd/.gitlab-ci.yml`

- **GitHub Actions**: `.github/workflows/deploy.yml`



Example GitHub Actions workflow:

```yaml

name: Deploy NGINX



on:

  push:

    branches: [ main ]

  pull_request:

    branches: [ main ]



jobs:

  deploy:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v2

      - name: Deploy to Production

        run: make deploy-prod

        env:

          KUBECONFIG: ${{ secrets.KUBECONFIG }}

```



## 📊 Monitoring



### Metrics Collection



The framework includes comprehensive monitoring:



1. **Prometheus Metrics**

   - NGINX stub_status metrics

   - Custom application metrics

   - System metrics (CPU, memory, disk)



2. **Grafana Dashboards**

   - NGINX Overview Dashboard

   - Security Dashboard

   - Performance Dashboard

   - Business Metrics Dashboard



### Accessing Dashboards



```bash

# Port forward Grafana

kubectl port-forward svc/grafana 3000:3000 -n monitoring



# Access at http://localhost:3000

# Default credentials: admin / admin

```



### Alerting Configuration



Alerts are configured in `monitoring/prometheus/alerts.yml`:



```yaml

groups:

  - name: nginx_alerts

    rules:

      - alert: HighErrorRate

        expr: rate(nginx_http_requests_total{status=~"5.."}[5m]) > 0.05

        for: 5m

        labels:

          severity: critical

        annotations:

          summary: "High error rate on NGINX"

          description: "Error rate is {{ $value }} per second"

```



## 🔒 Security



### Security Features



1. **Automated Security Scanning**

   ```bash

   # Run security scan

   ./scripts/security-scan.sh --full

   

   # Check for vulnerabilities

   trivy image nginx:1.24.0

   ```



2. **Compliance Checks**

   ```bash

   # Run compliance checks

   ./scripts/compliance-check.sh --standard pci-dss

   ```



3. **Secret Management**

   ```bash

   # Store secrets securely

   ansible-vault encrypt environments/production/secrets.yml

   ```



### Security Headers



Automatically configured security headers:

- Content-Security-Policy (CSP)

- Strict-Transport-Security (HSTS)

- X-Content-Type-Options

- X-Frame-Options

- Referrer-Policy

- Permissions-Policy



## 🚨 Disaster Recovery



### Backup Strategy



```bash

# Create backup

./scripts/backup.sh --full



# Restore from backup

./scripts/restore.sh --backup-file backup-20231201.tar.gz

```



### Recovery Procedures



1. **Infrastructure Recovery**

   ```bash

   # Recreate infrastructure

   terraform apply -var-file="environments/dr/terraform.tfvars"

   ```



2. **Configuration Recovery**

   ```bash

   # Restore configurations

   ansible-playbook playbooks/restore-config.yml

   ```



3. **Data Recovery**

   ```bash

   # Restore data from backup

   ./scripts/restore-data.sh --from-s3

   ```



## 🧪 Testing



### Test Suite



```bash

# Run all tests

make test-all



# Specific test types

make test-unit          # Unit tests

make test-integration   # Integration tests

make test-load          # Load tests

make test-security      # Security tests

```



### Load Testing with k6



```javascript

// tests/load-test/script.js

import http from 'k6/http';

import { check, sleep } from 'k6';



export let options = {

  stages: [

    { duration: '30s', target: 100 },

    { duration: '1m', target: 500 },

    { duration: '30s', target: 0 },

  ],

  thresholds: {

    http_req_duration: ['p(95)<500'],

    http_req_failed: ['rate<0.01'],

  },

};



export default function () {

  let res = http.get('https://example.com');

  check(res, {

    'status is 200': (r) => r.status === 200,

    'response time < 500ms': (r) => r.timings.duration < 500,

  });

  sleep(1);

}

```



## 🤝 Contributing



We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.



### Development Workflow



1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Run tests

5. Submit a pull request



### Code Standards



- Follow existing code style

- Write comprehensive tests

- Update documentation

- Keep commits atomic



## 📄 License



This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.



## 🆘 Support



### Getting Help



- 📚 [Documentation](https://docs.example.com/nginx-automation)

- 🐛 [Issue Tracker](https://github.com/your-org/nginx-automation/issues)

- 💬 [Slack Channel](https://slack.example.com/nginx-automation)

- 📧 [Email Support](mailto:support@example.com)



### Common Issues



Check our [Troubleshooting Guide](docs/troubleshooting.md) for common problems and solutions.



### Commercial Support



For enterprise support, contact [enterprise@example.com](mailto:enterprise@example.com).



## 🎯 Roadmap



- [x] Initial release with core features

- [ ] Multi-cloud support (AWS, GCP, Azure)

- [ ] Service mesh integration (Istio, Linkerd)

- [ ] AI-powered anomaly detection

- [ ] GitOps workflow enhancement

- [ ] Extended compliance frameworks (SOC2, ISO27001)



## 📈 Performance Benchmarks



| Metric | Value | Target |

|--------|-------|--------|

| Requests/sec | 15,000 | 10,000 |

| Latency (p95) | 45ms | 100ms |

| Availability | 99.99% | 99.95% |

| Error Rate | 0.01% | 0.1% |



---



## 🏆 Acknowledgments



- NGINX Inc. for the amazing web server

- The open-source community for various tools and libraries

- Our contributors and maintainers



## 🔗 Related Projects



- [nginx-prometheus-exporter](https://github.com/nginxinc/nginx-prometheus-exporter)

- [cert-manager](https://cert-manager.io/)

- [prometheus-nginx-exporter](https://github.com/discordianfish/nginx-exporter)



---



**Maintained by**: Solomon Kassa  

**Last Updated**: January 2026

**Version**: 1.0.0



---





  Need help? Check our FAQ or open an issue






  Built with ❤️ by Solomon Kassa