{"id":25841272,"url":"https://github.com/amirk1998/monitoring-stack","last_synced_at":"2026-05-13T06:37:03.259Z","repository":{"id":279270768,"uuid":"938244160","full_name":"amirk1998/monitoring-stack","owner":"amirk1998","description":"A comprehensive Docker-based monitoring stack featuring Prometheus, Grafana, Loki, and Alertmanager. This plug-and-play solution provides metrics collection, log aggregation, visualization, and alerting capabilities for modern infrastructure and applications.","archived":false,"fork":false,"pushed_at":"2025-02-24T17:59:54.000Z","size":393,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-24T18:28:25.310Z","etag":null,"topics":["cadvisor","grafana","grafana-dashboard","log","logmanagement","loki","monitoring","nodeexporter","prometheus","prometheus-exporter"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amirk1998.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-24T16:41:40.000Z","updated_at":"2025-02-24T17:59:58.000Z","dependencies_parsed_at":"2025-02-24T18:39:57.269Z","dependency_job_id":null,"html_url":"https://github.com/amirk1998/monitoring-stack","commit_stats":null,"previous_names":["amirk1998/monitoring-stack"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amirk1998%2Fmonitoring-stack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amirk1998%2Fmonitoring-stack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amirk1998%2Fmonitoring-stack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amirk1998%2Fmonitoring-stack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amirk1998","download_url":"https://codeload.github.com/amirk1998/monitoring-stack/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241319561,"owners_count":19943554,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cadvisor","grafana","grafana-dashboard","log","logmanagement","loki","monitoring","nodeexporter","prometheus","prometheus-exporter"],"created_at":"2025-03-01T05:22:58.254Z","updated_at":"2026-05-13T06:36:58.236Z","avatar_url":"https://github.com/amirk1998.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DevOps Monitoring Stack\n\nA comprehensive, Docker-based monitoring solution for modern infrastructure and applications. This stack provides full observability with metrics, logs, and alerts using industry-standard open-source tools.\n\n\u003c!-- ![Grafana Dashboard](https://via.placeholder.com/800x400?text=Monitoring+Dashboard) --\u003e\n\n## 🔍 Overview\n\nThis project delivers a complete monitoring infrastructure as code, allowing you to quickly deploy a production-ready monitoring solution. The stack includes:\n\n- **Metrics collection**: Prometheus, Node Exporter, cAdvisor, Telegraf\n- **Log aggregation**: Loki, Promtail\n- **Alerting**: Alertmanager with email and Slack integration\n- **Visualization**: Grafana with pre-configured dashboards\n- **Endpoint monitoring**: Blackbox Exporter for HTTP/HTTPS/TCP checks\n\nThis monitoring solution is designed to provide immediate visibility into your infrastructure while remaining highly customizable to meet specific requirements.\n\n## 🚀 Features\n\n- **Zero-configuration deployment** - Works out of the box with sensible defaults\n- **Environment-based configuration** - Easily customize via `.env` file\n- **Template-based configuration files** - All configuration files use templates for easy customization\n- **Comprehensive metrics collection** - From system metrics to container stats\n- **Centralized logging** - Aggregate and search logs from all systems\n- **Multi-channel alerting** - Email, Slack, and more\n- **Pre-built dashboards** - Hit the ground running with ready-to-use dashboards\n- **Secure by default** - Authentication enabled for all components\n- **Docker-compose deployment** - Simple to deploy and manage\n- **Development-friendly** - Includes MailHog for testing email alerts locally\n\n## 📋 Requirements\n\n- Docker Engine (19.03.0+)\n- Docker Compose (1.27.0+)\n- 2GB+ RAM recommended\n- 10GB+ disk space\n\n## 🛠️ Quick Start\n\n1. **Clone the repository**\n\n   ```bash\n   git clone https://github.com/amirk1998/monitoring-stack.git\n   cd devops-monitoring-stack\n   ```\n\n2. **Configure your environment**\n\n   ```bash\n   cp .env.example .env\n   # Edit .env file with your preferred settings\n   ```\n\n3. **Generate configuration files**\n\n   ```bash\n   ./setup-config.sh\n   ```\n\n4. **Launch the stack**\n\n   ```bash\n   docker-compose up -d\n   ```\n\n5. **Access the dashboards**\n\n   - Grafana: http://localhost:3000 (default credentials: admin/ChangeMe123!)\n   - Prometheus: http://localhost:9090\n   - Alertmanager: http://localhost:9093\n   - MailHog (development only): http://localhost:8025\n\n## 📊 Stack Components\n\n### Core Monitoring\n\n| Component        | Description                                | Port |\n| ---------------- | ------------------------------------------ | ---- |\n| **Prometheus**   | Time-series database and metrics collector | 9090 |\n| **Grafana**      | Visualization and dashboarding platform    | 3000 |\n| **Alertmanager** | Alert handling and routing                 | 9093 |\n\n### Metrics Collection\n\n| Component             | Description                                      | Port |\n| --------------------- | ------------------------------------------------ | ---- |\n| **Node Exporter**     | Host system metrics (CPU, memory, disk, network) | 9100 |\n| **cAdvisor**          | Container metrics and resource usage             | 8080 |\n| **Blackbox Exporter** | Probes endpoints over HTTP, HTTPS, DNS, TCP      | 9115 |\n| **Telegraf**          | Pluggable metrics collection agent               | 9273 |\n\n### Logging\n\n| Component    | Description                 | Port |\n| ------------ | --------------------------- | ---- |\n| **Loki**     | Log aggregation system      | 3100 |\n| **Promtail** | Log collector and forwarder | -    |\n\n### Development Tools\n\n| Component   | Description                            | Port       |\n| ----------- | -------------------------------------- | ---------- |\n| **MailHog** | SMTP testing server with web interface | 1025, 8025 |\n\n## ⚙️ Configuration\n\n### Directory Structure\n\n```\n.\n├── alertmanager/               # Alertmanager configuration\n├── blackbox_exporter/          # Blackbox Exporter configuration\n├── grafana/                    # Grafana dashboards and datasources\n├── loki/                       # Loki configuration\n├── prometheus/                 # Prometheus configuration and rules\n│   ├── alerts/                 # Alert rules\n│   └── ...\n├── promtail/                   # Promtail configuration\n├── telegraf/                   # Telegraf configuration\n├── docker-compose.yml          # Service definitions\n├── .env.example                # Example environment variables\n├── setup-config.sh             # Configuration generator script\n└── README.md                   # This file\n```\n\n### Environment Variables\n\nThe `.env` file controls key aspects of the monitoring stack:\n\n- Service ports\n- Credentials\n- Alerting channels\n- Retention settings\n- Resource limits\n\nSee `.env.example` for all available options.\n\n### Templates\n\nAll configuration files use templates (`.yml.template`, `.conf.template`) that are processed during setup:\n\n- Values from the `.env` file are substituted\n- Final configuration files are generated\n- Changes to templates require running `setup-config.sh` again\n\n## 📊 Dashboards\n\nThe stack comes with several pre-configured dashboards:\n\n| Dashboard                  | Description                                     |\n| -------------------------- | ----------------------------------------------- |\n| **Node Exporter Overview** | Host-level metrics (CPU, memory, disk, network) |\n| **Docker Containers**      | Container metrics from cAdvisor                 |\n| **Prometheus Stats**       | Prometheus performance and health               |\n| **Alertmanager Overview**  | Alert status and history                        |\n| **Loki Logs**              | Log exploration and search                      |\n\nTo add custom dashboards:\n\n1. Export dashboard JSON from Grafana\n2. Place in `grafana/provisioning/dashboards/`\n3. Update `grafana/provisioning/dashboards/dashboard.yml` if needed\n4. Restart Grafana: `docker-compose restart grafana`\n\n## 🔔 Alerting\n\n### Alert Channels\n\n- **Email**: Configure via SMTP settings in `.env`\n- **Slack**: Configure via webhook URL in `.env`\n- **Other integrations**: Can be added in `alertmanager/alertmanager.yml.template`\n\n### Alert Rules\n\n- Default rules are in `prometheus/alerts/custom_alerts.yml`\n- Add new rules by creating files in `prometheus/alerts/`\n- Rules are automatically picked up by Prometheus\n\nExample alert rule:\n\n```yaml\ngroups:\n  - name: host\n    rules:\n      - alert: HighCpuLoad\n        expr: 100 - (avg by(instance) (irate(node_cpu_seconds_total{mode=\"idle\"}[5m])) * 100) \u003e 80\n        for: 5m\n        labels:\n          severity: warning\n        annotations:\n          summary: High CPU load (instance {{ $labels.instance }})\n          description: CPU load is \u003e 80%\\n  VALUE = {{ $value }}\\n  LABELS = {{ $labels }}\n```\n\n## 🔄 Extending the Stack\n\n### Adding New Services to Monitor\n\n1. Add a new section to `prometheus/prometheus.yml.template`:\n\n```yaml\n- job_name: 'new-service'\n  static_configs:\n    - targets: ['new-service:9090']\n```\n\n2. Run `./setup-config.sh` to regenerate configurations\n3. Restart Prometheus: `docker-compose restart prometheus`\n\n### Adding Custom Exporters\n\n1. Add the exporter to `docker-compose.yml`:\n\n```yaml\ncustom-exporter:\n  image: custom-exporter:latest\n  ports:\n    - '9999:9999'\n  networks:\n    - monitoring\n```\n\n2. Add a scrape configuration to `prometheus/prometheus.yml.template`\n3. Run `./setup-config.sh`\n4. Restart the stack: `docker-compose up -d`\n\n## 🔐 Security Considerations\n\n### Authentication\n\n- Grafana: Protected by username/password (configured in `.env`)\n- Basic auth can be enabled for other components by editing their respective config templates\n\n### Network Security\n\n- Default configuration exposes ports to host\n- For production, consider:\n  - Using a reverse proxy with TLS\n  - Implementing network isolation\n  - Setting up firewall rules\n\n### Production Recommendations\n\n- Change all default passwords\n- Enable TLS for all connections\n- Use Docker secrets or Kubernetes secrets for sensitive values\n- Implement proper backup for data volumes\n\n## 🔍 Troubleshooting\n\n### Common Issues\n\n- **Loki fails to start**: Ensure schema and index type configuration match (see loki-config.yml)\n- **Prometheus can't scrape targets**: Check network connectivity and firewall rules\n- **Grafana doesn't show data**: Verify data source configuration and test connection\n- **Alerts not sending**: Check SMTP or webhook configuration\n\n### Logs\n\nView logs for any service:\n\n```bash\ndocker-compose logs -f [service_name]\n```\n\nExample:\n\n```bash\ndocker-compose logs -f prometheus\ndocker-compose logs -f loki\n```\n\n## 📚 Maintenance\n\n### Updating\n\nTo update the stack to the latest images:\n\n```bash\ndocker-compose pull\ndocker-compose up -d\n```\n\n### Backup\n\nBack up configuration and data:\n\n```bash\n# Configuration\ntar -czvf config-backup.tar.gz */*.yml */*.conf\n\n# Data volumes\ndocker run --rm -v prometheus_data:/data -v $(pwd):/backup alpine tar -czvf /backup/prometheus-data.tar.gz /data\ndocker run --rm -v grafana_data:/data -v $(pwd):/backup alpine tar -czvf /backup/grafana-data.tar.gz /data\ndocker run --rm -v loki_data:/data -v $(pwd):/backup alpine tar -czvf /backup/loki-data.tar.gz /data\n```\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Run the tests (if any)\n4. Commit your changes (`git commit -m 'Add some amazing feature'`)\n5. Push to the branch (`git push origin feature/amazing-feature`)\n6. Open a Pull Request\n\n## 📝 License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## 📚 Resources\n\n- [Prometheus Documentation](https://prometheus.io/docs/introduction/overview/)\n- [Grafana Documentation](https://grafana.com/docs/)\n- [Loki Documentation](https://grafana.com/docs/loki/latest/)\n- [AlertManager Documentation](https://prometheus.io/docs/alerting/latest/alertmanager/)\n- [Node Exporter Documentation](https://prometheus.io/docs/guides/node-exporter/)\n- [cAdvisor Documentation](https://github.com/google/cadvisor/blob/master/docs/README.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famirk1998%2Fmonitoring-stack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famirk1998%2Fmonitoring-stack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famirk1998%2Fmonitoring-stack/lists"}