infra/docs.md

🧠 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:

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:

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):

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:

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 🛠️