readme for Server Monitoring Stack

2025-10-21 20:13:31 +05:30
parent f26d447bca
commit 9f56f4bd32
1 changed files with 163 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,163 @@
+# 🏗️ Private Server Monitoring Stack — Aetoskia Infrastructure
+
+This repository defines a private, self-hosted server monitoring stack running on Raspberry Pi nodes and other servers, consisting of:
+
+* **Netdata** for system and container metrics
+* **Portainer** for container management and orchestration
+
+This setup allows a central **manager server** to monitor all nodes while providing dashboards and management UI accessible via HTTPS.
+
+---
+
+## 🧬 Services Overview
+
+| Service         | Role                                    | Port(s) | Depends On          |
+| --------------- | --------------------------------------- | ------- | ------------------- |
+| netdata         | System monitoring dashboard & master    | 7001    | —                   |
+| netdata_node    | Node agent streaming metrics to master  | 7003    | netdata (manager)   |
+| portainer       | Container management UI & API           | 7002    | —                   |
+| portainer_agent | Node agent for remote Docker management | 9001    | portainer (manager) |
+
+---
+
+## ⚙️ Service Details
+
+### 🐳 Netdata Manager
+
+Central monitoring server collecting metrics from all connected nodes and exposing dashboards.
+
+**Ports**
+
+* 7001 → 19999 — Web dashboard (HTTPS handled via reverse proxy)
+
+**Mounts**
+
+* `netdata_config:/etc/netdata` — Persistent Netdata configuration
+* `netdata_lib:/var/lib/netdata` — Persistent Netdata metrics database
+* `netdata_cache:/var/cache/netdata` — Cache storage
+
+**Environment**
+
+* `NETDATA_CLAIM_TOKEN` — Optional claim token for Netdata Cloud
+* `NETDATA_CLAIM_URL=https://app.netdata.cloud`
+
+**Profiles**
+
+* `netdata-manager` — Manager profile (always acts as manager + local node)
+
+---
+
+### 🐳 Netdata Node
+
+Agent container that streams metrics to the manager server.
+
+**Ports**
+
+* 7003 → 19999 — Local dashboard (optional)
+
+**Environment**
+
+* `NETDATA_STREAM_PARENT=https://netdata.aetoskia.com` — Manager endpoint
+* `NETDATA_CLAIM_TOKEN` — Optional claim token
+* `NETDATA_CLAIM_URL=https://app.netdata.cloud`
+
+**Profiles**
+
+* `netdata-node` — Node-only profile
+
+---
+
+### 🦾 Portainer Manager
+
+Central container management UI and API server, visualizing Docker nodes and stacks.
+
+**Ports**
+
+* 7002 → 9000 — Portainer web UI
+
+**Mounts**
+
+* `/var/run/docker.sock:/var/run/docker.sock:ro` — Access local Docker
+* `portainer_data:/data` — Persistent Portainer data
+
+**Profiles**
+
+* `portainer-manager` — Manager profile
+
+---
+
+### 🦾 Portainer Agent
+
+Node agent that registers with the Portainer manager to allow remote Docker management.
+
+**Ports**
+
+* 9001 → 9001 — Agent API
+
+**Mounts**
+
+* `/var/run/docker.sock:/var/run/docker.sock` — Access local Docker
+* `portainer_agent_data:/data` — Persistent agent data
+
+**Profiles**
+
+* `portainer-agent` — Node-only profile
+
+---
+
+## 🧬 Network Integration
+
+Ensure `/etc/hosts` on all relevant devices (Pi nodes, servers) includes:
+
+```
+192.168.1.35 netdata.aetoskia.com
+192.168.1.35 portainer.aetoskia.com
+```
+
+* **Netdata manager** receives metrics from `netdata_node` agents
+* **Portainer manager** manages `portainer_agent` nodes
+
+---
+
+## 🧠 Usage
+
+### Manager Server
+
+Start manager services (also acts as local node):
+
+```bash
+docker compose --profile netdata-manager --profile portainer-manager down --remove-orphans && docker compose --profile netdata-manager --profile portainer-manager up -d
+```
+
+### Node Server
+
+Start agent/node services:
+
+```bash
+docker compose --profile netdata-node --profile portainer-agent down --remove-orphans && docker compose --profile netdata-node --profile portainer-agent up -d
+```
+
+---
+
+## ✅ Quick Test Checklist
+
+| Component       | URL                                                                        | Expected Result                                         |
+| --------------- | -------------------------------------------------------------------------- | ------------------------------------------------------- |
+| Netdata Manager | [https://netdata.aetoskia.com:7001](https://netdata.aetoskia.com:7001)     | Dashboard showing metrics for manager + connected nodes |
+| Portainer       | [https://portainer.aetoskia.com:7002](https://portainer.aetoskia.com:7002) | Portainer UI showing manager + registered nodes         |
+| Netdata Node    | https://<node_ip>:7003                                                     | Node metrics accessible locally                         |
+| Portainer Agent | Internal agent API                                                         | Registered under manager UI                             |
+
+---
+
+## 🧠 Tips
+
+* **Manager profile** always acts as **manager + local node**.
+* **Node profile** only runs **agent containers**, never acts as manager.
+* Use **Docker Compose profiles** to cleanly separate roles.
+* Reverse proxy (HTTPS) is recommended for dashboard access.
+* Persistent mounts ensure that configuration and metrics survive container restarts.
+
+---
+
+© Aetoskia Internal Infrastructure — All rights reserved.