MeshMonitor

Appearance

GitHub Stars

Configuration Overview ​

MeshMonitor is designed to be flexible and adaptable to various deployment scenarios. This section covers all configuration options and deployment strategies.

Quick Start: Interactive Configurator

New! Use our Interactive Docker Compose Configurator to generate a customized docker-compose.yml and .env file for your specific setup. Just answer a few questions and get a ready-to-deploy configuration!

Supports: TCP/Network, BLE Bridge, Serial Bridge, reverse proxy, Virtual Node, and more.

Configuration Topics ​

Serial Bridge for USB/Serial Devices ​

Connect MeshMonitor to Serial or USB-connected Meshtastic devices using the Serial Bridge. Simple Docker-based TCP-to-Serial gateway with automatic device discovery.

BLE Bridge for Bluetooth Devices ​

Connect MeshMonitor to Bluetooth Low Energy (BLE) Meshtastic devices using the BLE Bridge. Perfect for portable devices and systems with Bluetooth support.

Virtual Node Server ​

Connect multiple Meshtastic mobile apps simultaneously through MeshMonitor's Virtual Node proxy. Configuration caching, message queuing, and connection stability for 3-5+ concurrent mobile clients.

Using meshtasticd ​

Learn how to configure MeshMonitor to work with meshtasticd, the virtual Meshtastic node daemon, perfect for testing and development without physical hardware.

SSO Setup ​

Configure Single Sign-On (SSO) authentication using OpenID Connect (OIDC) for enterprise deployments and centralized identity management.

Reverse Proxy ​

Set up NGINX, Apache, or other reverse proxies to handle SSL termination, load balancing, and secure external access to MeshMonitor.

HTTP vs HTTPS ​

Understand the differences between HTTP and HTTPS deployments, security considerations, and how to configure SSL/TLS certificates.

Production Deployment ​

Best practices and recommendations for deploying MeshMonitor in production environments, including high availability and monitoring.

Fail2ban Integration ​

Protect your instance from brute-force attacks using fail2ban. Includes setup guide, AbuseIPDB integration, and advanced configuration options.

Push Notifications ​

Configure push notifications for iOS, Android, and desktop browsers. Learn about HTTPS requirements, VAPID keys, and step-by-step setup guides for all platforms.

Custom Tile Servers ​

Configure custom map tile servers for offline operation, custom styling, or organizational branding. Supports both vector (.pbf) and raster (.png) tiles with TileServer GL, nginx caching proxy, or any standard XYZ tile server.

Environment Variables ​

MeshMonitor can be configured using environment variables. Here are the most important ones:

Required Variables ​

VariableDescriptionExample
MESHTASTIC_NODE_IPIP address of your Meshtastic node192.168.1.100

Optional Variables ​

VariableDescriptionDefault
PORTBackend server port3001
SESSION_SECRETSecret key for session encryption (REQUIRED in production)Auto-generated
NODE_ENVEnvironment mode (development or production)development
DATABASE_PATHSQLite database file path/data/meshmonitor.db
BASE_URLBase path if serving from subfolder (e.g., /meshmonitor)/ (root)
TZTimezone for log timestamps and scheduled tasksAmerica/New_York

Meshtastic Connection Variables ​

VariableDescriptionDefault
MESHTASTIC_NODE_IPIP address of your Meshtastic node192.168.1.100
MESHTASTIC_TCP_PORTTCP port for Meshtastic connection4403
MESHTASTIC_STALE_CONNECTION_TIMEOUTConnection timeout in milliseconds before reconnecting30000 (30 seconds)

Virtual Node Variables ​

VariableDescriptionDefault
ENABLE_VIRTUAL_NODEEnable Virtual Node Server for multiple mobile app connectionsfalse
VIRTUAL_NODE_PORTTCP port for Virtual Node Server (mobile apps connect to this)4404
VIRTUAL_NODE_ALLOW_ADMIN_COMMANDSAllow admin commands (position, waypoint, trace route) through Virtual Nodefalse

See the Virtual Node Server guide for detailed configuration and usage.

Security & Reverse Proxy Variables ​

VariableDescriptionDefault
TRUST_PROXYTrust reverse proxy headers (required for HTTPS behind proxy)1 in production
COOKIE_SECURERequire HTTPS for cookiestrue in production
COOKIE_SAMESITECookie SameSite policy (strict, lax, or none)strict in production
SESSION_COOKIE_NAMECustom session cookie name (useful for multiple instances on same host)meshmonitor.sid
SESSION_MAX_AGESession cookie lifetime in milliseconds86400000 (24 hours)
SESSION_ROLLINGReset session expiry on each request (keeps active users logged in)true
ALLOWED_ORIGINSREQUIRED for HTTPS/reverse proxy: Comma-separated list of allowed CORS originshttp://localhost:8080, http://localhost:3001

Running Multiple Instances

If you're running multiple MeshMonitor instances on the same host (different ports), set SESSION_COOKIE_NAME to a unique value for each instance to avoid session cookie conflicts:

yaml
# First instance
- SESSION_COOKIE_NAME=meshmonitor-mf.sid
# Second instance
- SESSION_COOKIE_NAME=meshmonitor-lf.sid

Authentication Variables ​

VariableDescriptionDefault
DISABLE_ANONYMOUSDisable anonymous access - require login for all featuresfalse
DISABLE_LOCAL_AUTHDisable local username/password authentication (OIDC only)false
ADMIN_USERNAMEOverride default admin username on first runadmin

Rate Limiting Variables ​

VariableDescriptionDefault (Production)Default (Development)
RATE_LIMIT_APIMax API requests per 15 minutes1000 (~1 req/sec)10000
RATE_LIMIT_AUTHMax auth attempts per 15 minutes5100
RATE_LIMIT_MESSAGESMax messages per minute30100

Note: Rate limit violations are logged with IP address and path for troubleshooting. Adjust these values based on your usage patterns.

Access Logging Variables (for fail2ban) ​

VariableDescriptionDefault
ACCESS_LOG_ENABLEDEnable Apache-style access logging for fail2ban integrationfalse
ACCESS_LOG_PATHPath to access log file/data/logs/access.log
ACCESS_LOG_FORMATLog format (combined, common, or tiny)combined

Note: Requires bind mount for host access. See Fail2ban Integration for complete setup guide.

SSO Variables (OIDC) ​

VariableDescriptionDefault
OIDC_ISSUEROIDC issuer URLNone (required for SSO)
OIDC_CLIENT_IDOIDC client IDNone (required for SSO)
OIDC_CLIENT_SECRETOIDC client secretNone (required for SSO)
OIDC_REDIRECT_URICallback URL for OIDCNone (required for SSO)
OIDC_SCOPESSpace-separated OIDC scopes to requestopenid profile email
OIDC_AUTO_CREATE_USERSAutomatically create users on first SSO logintrue
OIDC_ALLOW_HTTPAllow HTTP for OIDC (development only, not secure)false

See the SSO Setup guide for detailed OIDC configuration.

Push Notification Variables (Web Push) ​

VariableDescriptionDefault
VAPID_PUBLIC_KEYVAPID public key for web push notificationsNone (required for push)
VAPID_PRIVATE_KEYVAPID private key for web push notificationsNone (required for push)
VAPID_SUBJECTVAPID subject (email or URL for contact)None (required for push)
PUSH_NOTIFICATION_TTLTime-to-live for push notifications in seconds (300-86400)3600 (1 hour)

See the Push Notifications guide for setup instructions and key generation.

System Management Variables ​

VariableDescriptionDefault
DATA_DIRRoot directory for application data/data
BACKUP_DIRDirectory for database backups/data/backups
SYSTEM_BACKUP_DIRDirectory for full system backups/data/system-backups
RESTORE_FROM_BACKUPPath to backup file to restore on startupNone
AUTO_UPGRADE_ENABLEDEnable automatic upgrades in Kubernetesfalse
APPRISE_CONFIG_DIRDirectory for Apprise notification configurationNone
DUPLICATE_KEY_SCAN_INTERVAL_HOURSHours between duplicate encryption key scans24

See the System Backup guide for backup and restore procedures.

Configuration Files ​

Docker Compose ​

For Docker deployments, configuration is typically done through environment variables in docker-compose.yml:

yaml
services:
  meshmonitor:
    image: meshmonitor:latest
    environment:
      - MESHTASTIC_NODE_IP=192.168.1.100
      - PORT=3000
      - SESSION_SECRET=your-secret-key-here
    ports:
      - "8080:8080"
    volumes:
      - meshmonitor_data:/app/data

Kubernetes (Helm) ​

For Kubernetes deployments, use the Helm chart values file:

yaml
# values.yaml
meshmonitor:
  nodeIp: "192.168.1.100"
  port: 3000

ingress:
  enabled: true
  host: meshmonitor.example.com
  tls:
    enabled: true

See the Production Deployment guide for complete Helm configuration.

Database Configuration ​

MeshMonitor uses SQLite for data storage by default. The database file is stored in the data/ directory.

Database Location ​

  • Docker: /app/data/meshmonitor.db (mounted as a volume)
  • Bare Metal: ./data/meshmonitor.db (relative to project root)

Backup and Migration ​

To backup your database:

bash
# Docker
docker cp meshmonitor:/app/data/meshmonitor.db ./backup.db

# Bare Metal
cp data/meshmonitor.db backup.db

Security Considerations ​

Session Secret ​

Always set a strong SESSION_SECRET in production:

bash
# Generate a secure random string
openssl rand -base64 32

Database Encryption ​

The database stores password hashes using bcrypt. User passwords are never stored in plain text.

HTTPS ​

Always use HTTPS in production environments. See the HTTP vs HTTPS guide for setup instructions.

Logging ​

MeshMonitor logs to stdout/stderr by default. Configure log aggregation in your deployment platform:

  • Docker: Use docker logs or configure a logging driver
  • Kubernetes: Logs are available via kubectl logs
  • Bare Metal: Redirect output to log files or use a process manager like systemd

Next Steps ​