Create README.md

2025-05-30 12:46:48 -04:00 · 2025-05-30 12:46:48 -04:00 · a542dfe613
parent 75357d31a2
commit a542dfe613
1 changed files with 124 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,124 @@
+# 🧠 Infrastructure Usage Guide
+
+This guide explains how to use the new Docker-based infrastructure stack deployed on **Unraid**, **Raspberry Pi**, and **Ubuntu**.
+
+---
+
+## 🚀 Starting the Monitoring Stack
+
+Each machine has a `start.sh` wrapper script that:
+- Runs `docker compose up -d`
+- Waits a few seconds for container readiness
+- Logs container IPs, ports, and web URLs
+
+To start:
+
+```bash
+chmod +x start.sh
+./start.sh
+```
+
+---
+
+## 📜 Service Overview
+
+The following services are deployed (excluding Pi-hole on Ubuntu):
+
+| Service           | Unraid | Pi | Ubuntu |
+|------------------|--------|----|-------|
+| Grafana          | ✅     | ❌ | ❌     |
+| Prometheus       | ✅     | ✅ | ✅     |
+| Loki             | ✅     | ✅ | ✅     |
+| Promtail         | ✅     | ✅ | ✅     |
+| Alertmanager     | ✅     | ✅ | ✅     |
+| Node Exporter    | ✅     | ✅ | ✅     |
+| Docker Exporter  | ✅     | ✅ | ✅     |
+| NGINX            | ✅     | ❌ | ❌     |
+| Pi-hole          | ❌     | ✅ | ❌     |
+
+---
+
+## 🌐 Defining IPs in Pi-hole
+
+Pi-hole is used for internal DNS routing of your infrastructure services.
+
+1. Open the **Pi-hole Admin Panel**
+2. Go to **Local DNS > DNS Records**
+3. Add A records like:
+
+```
+grafana.wyvern.bray.io -> 192.168.2.16
+prometheus.unraid.bray.io -> 192.168.2.28
+```
+
+> 💡 You can verify entries with `dig grafana.wyvern.bray.io`.
+
+---
+
+## 🌐 Defining IPs in NGINX
+
+NGINX is used to expose internal services via friendly URLs (e.g. `https://grafana.wyvern.bray.io`).
+
+1. Go to: `configs/nginx/conf.d/`
+2. Create or modify `.conf` files like:
+
+```nginx
+server {
+    listen 443 ssl;
+    server_name grafana.wyvern.bray.io;
+
+    ssl_certificate /etc/nginx/ssl/fullchain.pem;
+    ssl_certificate_key /etc/nginx/ssl/privkey.pem;
+
+    location / {
+        proxy_pass http://192.168.2.16:3000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+}
+```
+
+3. Reload NGINX (or restart the container):
+
+```bash
+docker restart nginx
+```
+
+---
+
+## 📦 Adding New Services
+
+1. Add a new service to `docker-compose.yml`
+2. Assign a static IP if needed
+3. Add a DNS record in Pi-hole
+4. Add a reverse proxy entry in NGINX
+
+---
+
+## 🧼 Resetting the Stack
+
+You can bring down and rebuild everything:
+
+```bash
+docker compose down
+docker compose up -d --build
+```
+
+This will recreate containers with preserved volumes. If you wipe volumes, services will reset.
+
+---
+
+## ✅ Final Tip: Keep a Network Sheet
+
+Keep a `infra-ip-map.md` or spreadsheet like:
+
+| Container      | Host    | Static IP     | Port | Domain                            |
+|----------------|---------|----------------|------|-----------------------------------|
+| Grafana        | Unraid  | 192.168.2.16   | 3000 | grafana.wyvern.bray.io            |
+| Prometheus     | Pi      | 192.168.2.28   | 9090 | prometheus.pi.bray.io             |
+| Loki           | Ubuntu  | 192.168.2.26   | 3100 | loki.ubuntu.bray.io               |
+| ...            | ...     | ...            | ...  | ...                               |
+
+---
+
+Happy hacking 🛠️