{"id":36954349,"url":"https://github.com/yeraze/meshmanager","last_synced_at":"2026-02-27T20:46:18.843Z","repository":{"id":328246257,"uuid":"1113119655","full_name":"Yeraze/meshmanager","owner":"Yeraze","description":"A tool for monitoring multiple MeshMonitor instances","archived":false,"fork":false,"pushed_at":"2026-01-08T00:14:41.000Z","size":821,"stargazers_count":7,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-12T17:13:32.640Z","etag":null,"topics":["meshtastic"],"latest_commit_sha":null,"homepage":"https://meshmanager.org/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Yeraze.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-09T14:47:35.000Z","updated_at":"2026-01-08T00:14:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Yeraze/meshmanager","commit_stats":null,"previous_names":["yeraze/meshmanager"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/Yeraze/meshmanager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yeraze%2Fmeshmanager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yeraze%2Fmeshmanager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yeraze%2Fmeshmanager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yeraze%2Fmeshmanager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Yeraze","download_url":"https://codeload.github.com/Yeraze/meshmanager/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yeraze%2Fmeshmanager/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28385798,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T12:01:30.995Z","status":"ssl_error","status_checked_at":"2026-01-13T12:00:09.625Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["meshtastic"],"created_at":"2026-01-13T13:00:03.431Z","updated_at":"2026-01-13T13:00:04.590Z","avatar_url":"https://github.com/Yeraze.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/public/images/logo.png\" alt=\"MeshManager Logo\" width=\"200\"\u003e\n\u003c/p\u003e\n\n# MeshManager\n\n[![Tests](https://github.com/Yeraze/meshmanager/actions/workflows/tests.yml/badge.svg)](https://github.com/Yeraze/meshmanager/actions/workflows/tests.yml)\n[![Release](https://github.com/Yeraze/meshmanager/actions/workflows/release.yml/badge.svg)](https://github.com/Yeraze/meshmanager/actions/workflows/release.yml)\n[![Docker](https://img.shields.io/badge/docker-ghcr.io-blue?logo=docker)](https://ghcr.io/yeraze/meshmanager)\n[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)\n\nManagement and oversight application for aggregating data from multiple MeshMonitor instances and Meshtastic MQTT servers.\n\n## Features\n\n- Aggregate data from multiple MeshMonitor instances and MQTT brokers\n- Interactive Leaflet map showing all nodes across all sources\n- Prometheus-compatible metrics endpoint for monitoring\n- OIDC authentication for admin access\n- Configurable data retention policies\n- Catppuccin-themed dark UI\n\n## Quick Start\n\n### Development (Single Command)\n\nRun the entire stack with a single command:\n\n```bash\ndocker compose -f docker-compose.dev.yml up -d --build\n```\n\nAccess the application at http://localhost:8080\n\nThis starts:\n- PostgreSQL database\n- FastAPI backend\n- React frontend\n- Nginx reverse proxy\n\nTo view logs:\n```bash\ndocker compose -f docker-compose.dev.yml logs -f\n```\n\nTo stop:\n```bash\ndocker compose -f docker-compose.dev.yml down\n```\n\n### Production (Pre-built Images)\n\nThe easiest way to deploy MeshManager is using pre-built Docker images:\n\n1. Create a `docker-compose.yml`:\n   ```yaml\n   services:\n     postgres:\n       image: postgres:16-alpine\n       environment:\n         POSTGRES_DB: meshmanager\n         POSTGRES_USER: meshmanager\n         POSTGRES_PASSWORD: meshmanager\n       volumes:\n         - postgres_data:/var/lib/postgresql/data\n       healthcheck:\n         test: [\"CMD-SHELL\", \"pg_isready -U meshmanager\"]\n         interval: 10s\n         timeout: 5s\n         retries: 5\n       restart: unless-stopped\n\n     meshmanager:\n       image: ghcr.io/yeraze/meshmanager:latest\n       ports:\n         - \"8080:8000\"\n       environment:\n         DATABASE_URL: postgresql+asyncpg://meshmanager:meshmanager@postgres/meshmanager\n         SESSION_SECRET: your-secret-here  # Generate with: openssl rand -hex 32\n       depends_on:\n         postgres:\n           condition: service_healthy\n       restart: unless-stopped\n\n   volumes:\n     postgres_data:\n   ```\n\n2. Start the stack:\n   ```bash\n   docker compose up -d\n   ```\n\n3. Access the application at http://localhost:8080\n\nTo use a specific version instead of `latest`:\n```yaml\nimage: ghcr.io/yeraze/meshmanager:0.5.0\n```\n\n### Production (Build from Source)\n\nIf you prefer to build the images yourself:\n\n1. Clone the repository and configure:\n   ```bash\n   git clone https://github.com/Yeraze/meshmanager.git\n   cd meshmanager\n   cp .env.example .env\n   # Edit .env with your settings\n   ```\n\n2. Start the production environment:\n   ```bash\n   docker compose up -d\n   ```\n\n3. Access the application at http://localhost:8080\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `MESHMANAGER_VERSION` | Docker image version (prebuilt only) | `latest` |\n| `POSTGRES_PASSWORD` | PostgreSQL password | `meshmanager` |\n| `SESSION_SECRET` | Session signing secret (required) | - |\n| `OIDC_ISSUER` | OIDC provider URL | - |\n| `OIDC_CLIENT_ID` | OIDC client ID | - |\n| `OIDC_CLIENT_SECRET` | OIDC client secret | - |\n| `OIDC_REDIRECT_URI` | OIDC callback URL | - |\n| `LOG_LEVEL` | Logging level | `INFO` |\n| `HTTP_PORT` | HTTP port | `8080` |\n\n### OIDC Authentication\n\nTo enable OIDC authentication:\n\n1. Configure your OIDC provider (Keycloak, Auth0, etc.)\n2. Set the OIDC environment variables\n3. The first user to log in becomes an admin\n\nWithout OIDC configured, the application runs in read-only mode.\n\n## API Endpoints\n\n### Public\n\n- `GET /health` - Health check\n- `GET /metrics` - Prometheus metrics\n- `GET /api/sources` - List sources (names only)\n- `GET /api/nodes` - List all nodes\n\n### Admin (requires authentication)\n\n- `GET /api/admin/sources` - List sources with full config\n- `POST /api/admin/sources/meshmonitor` - Add MeshMonitor source\n- `POST /api/admin/sources/mqtt` - Add MQTT source\n- `DELETE /api/admin/sources/{id}` - Remove source\n\n## Prometheus Metrics\n\nThe `/metrics` endpoint exposes:\n\n### Source Metrics\n- `meshmanager_source_healthy` - Source collection status (1=healthy, 0=error)\n- `meshmanager_source_last_collection_timestamp` - Last successful collection timestamp\n\n### Node Metrics\n- `meshmanager_node_battery_level` - Node battery level (0-100)\n- `meshmanager_node_voltage` - Node voltage\n- `meshmanager_node_last_heard_timestamp` - Node last heard timestamp (Unix seconds)\n- `meshmanager_node_channel_utilization` - Node channel utilization (0-100)\n\n### Network Metrics\n- `meshmanager_active_nodes_total` - Active nodes per source (heard in last hour)\n- `meshmanager_nodes_total` - Total nodes ever seen per source\n- `meshmanager_messages_last_hour` - Messages received in last hour\n\n### Database Metrics\n- `meshmanager_db_rows_total` - Database row counts by table (nodes, messages, telemetry, traceroutes)\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│                         MeshManager                                 │\n├─────────────────────────────────────────────────────────────────────┤\n│  ┌───────────────────────────────────┐  ┌─────────────┐             │\n│  │         meshmanager               │  │  PostgreSQL │             │\n│  │  (FastAPI + React SPA bundled)    │◄─┤   Database  │             │\n│  └──────────────┬────────────────────┘  └─────────────┘             │\n│                 │                                                   │\n│    ┌────────────┼────────────────┐                                  │\n│    ▼            ▼                ▼                                  │\n│  ┌──────────┐  ┌──────────┐  ┌──────────┐                           │\n│  │MeshMonitor│ │MeshMonitor│ │   MQTT   │                           │\n│  │ Collector │ │ Collector │ │ Collector│                           │\n│  └──────────┘  └──────────┘  └──────────┘                           │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n## Development\n\n### Backend\n\n```bash\ncd backend\npython -m venv .venv\nsource .venv/bin/activate\npip install -e \".[dev]\"\nuvicorn app.main:app --reload\n```\n\n### Frontend\n\n```bash\ncd frontend\nnpm install\nnpm run dev\n```\n\n### Running Tests\n\n```bash\n# Backend\ncd backend\npytest\n\n# Frontend\ncd frontend\nnpm run lint\n```\n\n## License\n\nBSD-3-Clause\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyeraze%2Fmeshmanager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyeraze%2Fmeshmanager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyeraze%2Fmeshmanager/lists"}