mirror of
https://github.com/ajvpot/meshexplorer.git
synced 2026-06-12 02:04:49 +02:00
Alex Vanderpot
78bf1c5855
Bundle Grafana (127.0.0.1:3000) with the grafana-clickhouse-datasource plugin and an auto-provisioned ClickHouse datasource using the read-only user. Adds GRAFANA_ADMIN_PASSWORD to .env.example. Verified: datasource health returns OK. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
83 lines
3.3 KiB
Markdown
83 lines
3.3 KiB
Markdown
# MeshExplorer
|
|
|
|
A real-time map, chat client, and packet-analysis tool for **MeshCore** mesh
|
|
networks. This repository ships the whole stack so it can be brought up with a
|
|
single `docker compose up`:
|
|
|
|
| Component | Path | Description |
|
|
|-----------|------|-------------|
|
|
| Web app | [`meshexplorer/`](./meshexplorer) | Next.js UI + API (map, chat, stats, packet analysis) |
|
|
| Ingest + DB | [`ingest/`](./ingest) | Go MeshCore MQTT→ClickHouse ingest, ClickHouse image, and SQL migrations |
|
|
| Discord relay | [`meshexplorer/`](./meshexplorer) (`Dockerfile.bot`) | Optional bot that relays MeshCore channel messages to Discord |
|
|
| Grafana | [`grafana/`](./grafana) | Dashboards with a pre-provisioned ClickHouse datasource (read-only user), on `127.0.0.1:3000` |
|
|
|
|
## Architecture
|
|
|
|
```
|
|
MQTT brokers (you configure)
|
|
│
|
|
▼
|
|
┌──────────────┐ ┌──────────────┐
|
|
│ meshcoreingest│──▶│ ClickHouse │◀── migrate (one-shot, applies schema)
|
|
└──────────────┘ └──────┬───────┘
|
|
│ (readonly user)
|
|
┌──────────┴──────────┐
|
|
▼ ▼ ▼
|
|
meshexplorer discord-bot grafana
|
|
(web UI :3001) (--profile bot) (:3000)
|
|
```
|
|
|
|
## Quick start
|
|
|
|
Requirements: Docker + Docker Compose.
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit .env — at minimum set:
|
|
# CLICKHOUSE_PASSWORD (read/write user, used by ingest + migrations)
|
|
# MQTT_BROKERS (JSON array of meshcore MQTT brokers to ingest from)
|
|
# Optional, for the Discord relay: DISCORD_WEBHOOK_URL (+ run with --profile bot)
|
|
|
|
docker compose up --build
|
|
```
|
|
|
|
Then open <http://localhost:3001>.
|
|
|
|
Startup order is handled automatically: ClickHouse becomes healthy → `migrate`
|
|
applies the schema and exits → `meshcoreingest` and `meshexplorer` start.
|
|
|
|
To also run the Discord relay:
|
|
|
|
```bash
|
|
docker compose --profile bot up --build
|
|
```
|
|
|
|
## Configuration
|
|
|
|
All configuration is via environment variables in `.env` (see
|
|
[`.env.example`](./.env.example) for the full list and defaults). Highlights:
|
|
|
|
- **ClickHouse** — two accounts. The read/write `default` user
|
|
(`CLICKHOUSE_PASSWORD`) is used by the ingest daemon and the migration runner;
|
|
the `readonly` user (`CLICKHOUSE_READONLY_PASSWORD`) is used by the web app and
|
|
the Discord bot. ClickHouse is only published to `127.0.0.1` for debugging and
|
|
is otherwise reachable only on the internal `meshnet` network.
|
|
- **MQTT_BROKERS** — a JSON array; each entry is
|
|
`{ "url", "username", "password", "topics" }` (`topics` defaults to
|
|
`["meshcore/#"]`). The ingest daemon exits with a clear error if this is unset,
|
|
so configure at least one broker.
|
|
|
|
## Development
|
|
|
|
Each component can be run on its own:
|
|
|
|
- Web app: see [`meshexplorer/README.md`](./meshexplorer/README.md)
|
|
(`npm install && npm run dev`).
|
|
- Ingest: see [`ingest/README.md`](./ingest/README.md) (`go build ./...`).
|
|
|
|
## Security notes
|
|
|
|
- `.env` is gitignored — keep real credentials out of version control.
|
|
- If you previously used the bundled defaults, rotate any secrets before going
|
|
to production.
|