MeshMonitor

A comprehensive web application for monitoring Meshtastic mesh networks over IP. Built with React, TypeScript, and Node.js, featuring a beautiful Catppuccin Mocha dark theme and persistent SQLite database storage.

Documentation

For complete documentation, visit meshmonitor.org

• Getting Started Guide - Installation and quick start
• FAQ - Frequently asked questions and troubleshooting
• Configuration - Detailed configuration options
• Development - Contributing and development setup

Quick Start

Get MeshMonitor running in 60 seconds:

# 1. Create docker-compose.yml
cat > docker-compose.yml << 'EOF'
services:
  meshmonitor:
    image: ghcr.io/yeraze/meshmonitor:latest
    ports:
      - "8080:3001"
    volumes:
      - meshmonitor-data:/data
    environment:
      - MESHTASTIC_NODE_IP=192.168.1.100  # Change to your node's IP
    restart: unless-stopped

volumes:
  meshmonitor-data:
EOF

# 2. Start MeshMonitor
docker compose up -d

# 3. Open http://localhost:8080

Default login: admin / changeme (change after first login!)

For detailed installation instructions, configuration options, and deployment scenarios, see the Getting Started Guide.

Key Features

• Real-time Mesh Monitoring - Live node discovery, telemetry, and message tracking
• Modern UI - Catppuccin theme with message reactions and threading
• Interactive Maps - Node positions and network topology visualization
• Persistent Storage - SQLite database with export/import capabilities
• Notifications - Web Push and Apprise integration for 100+ services
• Authentication - Local and OIDC/SSO support with RBAC
• Security Monitoring - Encryption key analysis and vulnerability detection
• Device Configuration - Full node configuration UI
• Docker Ready - Pre-built multi-architecture images
• 🆕 One-click Self-Upgrade - Automatic upgrades from the UI with backup and rollback
• 🆕 System Backup & Restore - Complete disaster recovery with automated backups

For a complete feature list and technical details, visit meshmonitor.org.

Development

Prerequisites

• Node.js 20+ or 22+ (Node.js 18 is deprecated)
• Docker (recommended) or local Node.js environment
• A Meshtastic device with WiFi/Ethernet connectivity

Local Development

# Clone with submodules
git clone --recurse-submodules https://github.com/Yeraze/meshmonitor.git
cd meshmonitor

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your Meshtastic node's IP address

# Start development servers
npm run dev:full

This starts both the React dev server (port 5173) and the Express API server (port 3001).

Available Scripts

Development:

• npm run dev - Start React development server
• npm run dev:server - Start Express API server
• npm run dev:full - Start both development servers
• npm run build - Build React app for production
• npm run build:server - Build Express server for production

Testing & Quality:

• npm run test - Run tests in watch mode
• npm run test:run - Run all tests once
• npm run test:coverage - Generate coverage report
• npm run lint - Run ESLint
• npm run typecheck - Run TypeScript compiler checks

Technology Stack

Frontend:

• React 19 with TypeScript
• Vite 7 (build tool)
• CSS3 with Catppuccin theme

Backend:

• Node.js with Express 5
• TypeScript
• better-sqlite3 (SQLite driver)

DevOps:

• Docker with multi-stage builds
• Docker Compose for orchestration
• GitHub Container Registry for images

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Development setup
• Testing requirements
• Code style guidelines
• Pull request process
• CI/CD workflows

Quick start:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes and add tests
4. Run tests locally (npm run test:run)
5. Commit with conventional commits (feat: add amazing feature)
6. Push and create a Pull Request

License

This project is licensed under the BSD-3-Clause License - see the LICENSE file for details.

Acknowledgments

• Meshtastic - Open source mesh networking
• Catppuccin - Soothing pastel theme
• React - Frontend framework
• better-sqlite3 - SQLite driver

Star History

---

MeshMonitor - Monitor your mesh, beautifully. 🌐✨

This application was entirely vibe coded with Claude Code.