NetWatcher is an open-source distributed network monitoring platform consisting of three components:
- Controller – Go backend (Iris framework) with REST API and WebSocket server
- Panel – Vue 3 frontend for dashboards, agent management, and visualization
- Agent – Go daemon that executes monitoring probes and reports data
The system uses PostgreSQL for metadata storage and ClickHouse for time-series probe data.
# Clone the repository
git clone https://github.com/netwatcherio/netwatcher-oss.git
cd netwatcher-oss
# Start infrastructure with Docker
docker-compose up -d
# Configure and run controllercd controller
cp .env.example .env
# Edit .env with your settings
go run .# In another terminal, run the panelcd panel
npm install
npm run devSee docs/development.md for detailed setup instructions.
| Document | Description |
|---|---|
| Architecture | System design and data flow |
| API Reference | REST API endpoints with required roles |
| Data Models | Database schemas and types |
| Deployment | Production deployment guide |
| Development | Setup, building, and testing |
| Permissions | Role-based access control |
| Panel Architecture | Frontend design and patterns |
| Agent Probes | Probe types and configuration |
| TrafficSim | Inter-agent traffic simulation |
| Alerting | Alert rules and notifications |
# App settings
LISTEN=0.0.0.0:8080
KEY=<jwt-signing-key># Required: 32+ chars
PIN_PEPPER=<pin-pepper># Required: random string# PostgreSQL
DB_DRIVER=postgres
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=netwatcher
POSTGRES_PASSWORD=<password>
POSTGRES_DB=netwatcher
# ClickHouse
CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=9000
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=
CLICKHOUSE_DB=netwatcherSee controller/.env.example for all options.
CONTROLLER_ENDPOINT=https://api.netwatcher.ioversion: '3.8'services:
controller:
build: ./controllerenvironment:
LISTEN: "0.0.0.0:8080"DB_DRIVER: "postgres"POSTGRES_HOST: "postgres"KEY: "${JWT_SECRET}"depends_on:
- postgres
- clickhousepanel:
build: ./panelports:
- "3000:3000"postgres:
image: postgres:14environment:
POSTGRES_PASSWORD: ${PG_PASSWORD}volumes:
- pgdata:/var/lib/postgresql/dataclickhouse:
image: clickhouse/clickhouse-server:latestvolumes:
- chdata:/var/lib/clickhousecaddy:
image: caddy:2-alpineports:
- "80:80"
- "443:443"volumes:
- ./Caddyfile:/etc/caddy/Caddyfilevolumes:
pgdata:
chdata:NetWatcher uses role-based access control (RBAC) for workspace-scoped operations:
| Role | Level | Capabilities |
|---|---|---|
| OWNER | 4 | Full control, delete workspace, transfer ownership |
| ADMIN | 3 | Manage members, delete agents & probes |
| USER | 2 | Create/edit agents and probes |
| VIEWER | 1 | Read-only access |
See docs/permissions.md for the complete permission matrix.
| Type | Description |
|---|---|
| MTR | Multi-hop traceroute with per-hop latency and loss |
| PING | ICMP ping with RTT statistics |
| DNS | DNS resolution monitoring with query time metrics |
| SPEEDTEST | Download/upload speed measurements |
| SYSINFO | System information (CPU, memory, OS) |
| NETINFO | Network information (public IP, gateway, ISP) |
| TRAFFICSIM | Inter-agent traffic simulation |
netwatcher-oss/
├── agent/ # Monitoring agent daemon
├── controller/ # Backend API server
│ ├── internal/ # Business logic
│ └── web/ # HTTP routes & middleware
├── panel/ # Vue.js frontend
│ ├── src/
│ │ ├── composables/ # Vue composables
│ │ ├── router/ # Route guards
│ │ ├── services/ # API services
│ │ └── views/ # Page components
├── docs/ # Documentation
├── docker-compose.yml # Production deployment
├── docker-compose.dev.yml # Development (DB only)
└── Caddyfile # Reverse proxy config