MESHDASH – MESHTASTIC WEB DASHBOARD
INSTALLATION & CONFIGURATION GUIDE (R2.x)

MeshDash is a self-hosted web interface designed for managing Meshtastic mesh networks. It handles real-time packet monitoring, node management, messaging, and telemetry graphing. This guide focuses on a complete manual installation for Debian, Ubuntu, or Raspberry Pi OS.

SYSTEM PREREQUISITES

Before starting, ensure your system meets these requirements:

OS: Debian, Ubuntu, or Raspberry Pi OS (Architecture: amd64, armhf, or arm64).

Python: Version 3.9 or newer is required.

Software: You must have pip, venv, wget, and unzip installed.

Hardware: A Meshtastic device connected via USB Serial, TCP (network), or BLE.

RAM: 512MB minimum (1GB recommended for smoother database operations).

SYSTEM PREPARATION

Open your terminal and run the following commands to install necessary system tools:

Command: sudo apt update
Command: sudo apt install -y python3 python3-pip python3-venv wget unzip

DOWNLOADING MESHDASH

Choose a location for the dashboard. We recommend a folder in your home directory.

Command: mkdir -p ~/mesh-dash
Command: cd ~/mesh-dash

Now download the latest release from the official server. (Replace with the current version number, e.g., X.X.X):

Command: VERSION="X.X.X"
Command: wget "https://meshdash.co.uk/versions/VERSION/mesh-dash.zip"
Command: unzip mesh-dash.zip -d ./
Command: rm mesh-dash.zip

PYTHON ENVIRONMENT SETUP

Using a virtual environment prevents MeshDash dependencies from interfering with your system software.

Command: python3 -m venv venv
Command: source venv/bin/activate
Command: pip install --upgrade pip
Command: pip install -r requirements.txt

THE CONFIGURATION FILE (.mesh-dash_config)

CRITICAL STEP: You must manually create a file named .mesh-dash_config in the ~/mesh-dash folder. The dashboard will not start without it.

--- INITIAL ADMIN CREDENTIALS (REQUIRED FOR FIRST RUN) ---
The following two lines are the most important for a new install. Add them to the very top of your config file. The Python script will read these, create your account in the database, and then AUTOMATICALLY DELETE these lines from the file for your security.

INITIAL_ADMIN_USERNAME=admin
INITIAL_ADMIN_PASSWORD=your_secure_password_here

--- MAIN CONFIGURATION SETTINGS ---
Copy and paste the following settings into the file below the admin lines, adjusting the values to match your specific radio connection:

Connection Settings
MESHTASTIC_CONNECTION_TYPE=SERIAL
MESHTASTIC_SERIAL_PORT=/dev/ttyUSB0
MESHTASTIC_HOST=192.168.0.0
MESHTASTIC_PORT=4403

Web Server Settings
WEBSERVER_HOST=0.0.0.0
WEBSERVER_PORT=8000

Security
AUTH_SECRET_KEY=enter_a_long_random_string_here

Database and Logging
DB_PATH=meshtastic_data.db
LOG_LEVEL=INFO

LAUNCHING THE DASHBOARD

Ensure you are still inside your virtual environment (you should see 'venv' in your command prompt).

Command: python3 meshtastic_dashboard.py

Once started:

Open your web browser.

Navigate to http://your-ip-address:8000.

Log in using the INITIAL_ADMIN credentials you defined in the config file.

After logging in, check your .mesh-dash_config file; you will notice the admin username and password lines have been removed.

SETTING UP AUTO-START (SYSTEMD)

To make MeshDash start automatically when your computer boots, create a service file:

Command: sudo nano /etc/systemd/system/mesh-dash.service

Paste the following content into the file. Replace 'your_user' with your actual Linux username:

[Unit]
Description=MeshDash Service
After=network.target

[Service]
Type=simple
User=your_user
WorkingDirectory=/home/your_user/mesh-dash
EnvironmentFile=/home/your_user/mesh-dash/.mesh-dash_config
ExecStart=/home/your_user/mesh-dash/venv/bin/python /home/your_user/mesh-dash/meshtastic_dashboard.py
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

To activate the service:
Command: sudo systemctl daemon-reload
Command: sudo systemctl enable mesh-dash.service
Command: sudo systemctl start mesh-dash.service

TROUBLESHOOTING

Admin login fails: If you missed the first-run user creation, delete the 'meshtastic_data.db' file, re-add the INITIAL_ADMIN lines to your config, and restart the script.

Radio not found: For USB connections, ensure your user is in the 'dialout' group: sudo usermod -a -G dialout $USER (then log out and back in).

Port 8000 busy: Change the WEBSERVER_PORT in your config file to another number, like 8080.

SUPPORT & UPDATES

Official Website: https://meshdash.co.uk
License: GNU General Public License v3.0

For updates, you can use the System tab within the web dashboard to check for and install the latest versions automatically.