Installation

Mesh Info requires Python 3.9+ and RRDtool libraries. The following instructions include installing those dependencies.

Installation instructions for Raspberry Pi OS (tested on Bullseye). This will create a meshinfo user, install the application to /opt/mesh-info as that user (in a Python virtualenv), and create /var/lib/mesh-info for storing the application data.

Note

If you are interested in setting up Mesh Info for development, please see Development/Contributing.

sudo apt update
sudo apt install -y git librrd-dev python3 python3-dev python3-pip python3-venv rrdtool
sudo useradd meshinfo
sudo mkdir /opt/mesh-info /var/lib/mesh-info
sudo chown meshinfo: /opt/mesh-info /var/lib/mesh-info
sudo -u meshinfo git clone https://github.com/smsearcy/mesh-info.git /opt/mesh-info/src
sudo -u meshinfo python3 -m venv /opt/mesh-info/
sudo -u meshinfo /opt/mesh-info/bin/pip install -U pip wheel
cd /opt/mesh-info/src
sudo -u meshinfo /opt/mesh-info/bin/pip install -r requirements.txt -e .
sudo -u meshinfo /opt/mesh-info/bin/alembic upgrade head

To run a test scan, you can run the following (optionally specifying the name or IP of the local node, in case localnode.local.mesh does not resolve):

/opt/mesh-info/bin/meshinfo report [LOCAL_NODE]

If it is unable to connect to localnode.local.mesh, then you will need to create /opt/mesh-info/src/.env with the following (using the node’s address instead of 10.1.1.1) for the collector service to run:

MESH_INFO_LOCAL_NODE="10.1.1.1"

Tip

See Configuration for more details and options.

You can also do a test of the poller/collector to confirm database access and data folder. The --run-once option means it will poll the network once, save the results, and quit.

/opt/mesh-info/bin/meshinfo collector --run-once

While you could run the web service and collector via /opt/mesh-info/bin/meshinfo web and /opt/mesh-info/bin/meshinfo collecotr, it is advantageous to setup Systemd services to run automatically and a NGINX reverse proxy in front of the Python application.

Systemd Services

Create the following files and run the systemctl commands below to setup Mesh Info as system services.

Based on this documentation.

/etc/systemd/system/meshinfo-web.socket

[Unit]
Description=Mesh Info Socket

[Socket]
ListenStream=/run/mesh-info.sock
# Our service won't need permissions,
# since it inherits the file descriptor by socket activation
# so only NGINX daemon needs access
SocketUser=www-data
# Optionally restrict the socket permissions further
#SocketMode=600

[Install]
WantedBy=sockets.target

/etc/systemd/system/meshinfo-web.service

[Unit]
Description=Mesh Info Web Service
Requires=meshinfo-web.socket
After=network.target

[Service]
Type=simple
User=meshinfo
Group=meshinfo
Restart=no
RuntimeDirectory=meshinfo
WorkingDirectory=/opt/mesh-info/src
ExecStart=/opt/mesh-info/bin/python -m meshinfo web --bind=unix:/run/mesh-info.sock

[Install]
WantedBy=multi-user.target

/etc/systemd/system/meshinfo-collector.service

[Unit]
Description=Mesh Info Collector Service
After=network.target

[Service]
Type=simple
User=meshinfo
Group=meshinfo
Restart=no
RuntimeDirectory=meshinfo
WorkingDirectory=/opt/mesh-info/src
ExecStart=/opt/mesh-info/bin/python -m meshinfo collector

[Install]
WantedBy=multi-user.target

Run these commands to enable the services (so they run on future restarts) and start them now.

sudo systemctl enable --now meshinfo-web.service meshinfo-collector.service

NGINX Reverse Proxy

It is generally recommended to run the Python Gunicorn process (which is part of meshinfo web) behind a NGINX reverse proxy.

sudo apt install -y nginx-light

Create /etc/nginx/sites-available/mesh-info with the following content (setting the server_name directive to whatever name(s) and/or IP(s) Mesh Info should be served on):

upstream app_server {
    # fail_timeout=0 means we always retry an upstream even if it failed
    # to return a good HTTP response

    # for UNIX domain socket setups
    server unix:/run/mesh-info.sock fail_timeout=0;
}

server {
    server_name YOUR.SERVER.NAME ANOTHER.SERVER.NAME;
    listen 8080;

    gzip on;
    gzip_min_length 10000;  # compress content over 10KB
    gzip_types application/json;
    gzip_proxied any;

    # reverse proxy the Gunicorn app server
    location / {
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $http_host;

        # we don't want nginx trying to do something clever with
        # redirects, we set the Host: header above already.
        proxy_redirect off;
        proxy_pass http://app_server;
    }

    # server static files via NGINX
    location /static {
        root /opt/mesh-info/src/meshinfo;
    }
}

Now enable the site, test the config, and then reload NGINX (assuming no issues):

sudo ln -s /etc/nginx/sites-available/mesh-info /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Now you can verify it is working by connecting to http://your.server.name:8080.

Upgrading

To get the latest version of Mesh Info, run the following:

sudo systemctl stop meshinfo-web meshinfo-collector
cd /opt/mesh-info/src
sudo -u meshinfo git pull
sudo -u meshinfo /opt/mesh-info/bin/pip install -r requirements.txt
sudo -u meshinfo /opt/mesh-info/bin/alembic upgrade head
sudo systemctl restart meshinfo-web meshinfo-collector

Warning

Remember to check the the changelog before upgrading in case there are impactful changes.

Troubleshooting

Tips for some common problems.

502 Bad Gateway

This means that the NGINX web server is running, but it cannot connect to Mesh Info. To see what the Mesh Info web service is reporting, run sudo journalctl -u meshinfo-web.