Development/Contributing

Thank you for your interest in Mesh Info! Here are some instructions and pointers to get you setup for development.

Note

Mesh Info is only tested on Linux, so these instructions assume you are on Linux (although it could be a virtual machine or WSL).

On the todo list is providing some sample data to load in a development environment. For now, you will either need to connect the development machine to a mesh (at least temporarily), or use the export and import commands to load data.

Installing

For starters, you will need:

  • Python 3.9 or greater, with the “dev” or “devel” libraries

  • RRDtool libraries (librrd-dev on Debian/Ubuntu or rrdtool-devel on Fedora).

  • uv to manage the Python environment.

  • just to run various tasks.

  • Fork/clone the Git repository using your preferred tool and cd to the repository.

Then, setup the Python virtual environment and activate it:

uv sync
just migrate-db
. ./venv/bin/activate

Create a .env file in the mesh-info folder and add:

MESH_INFO_ENV="development"
# this is optional, but can be helpful
MESH_INFO_LOG_LEVEL="DEBUG"
# Set the node address if necessary
#MESH_INFO_LOCAL_NODE="10.1.1.1"

Tip

Setting the environment to development enables the Pyramid web framework’s debug toolbar and puts the data directories in the current user’s home folder.

To get data, either run uv run meshinfo collector or use uv run meshinfo import to import data.

Run the development web server via:

uv run meshinfo web

Tip

With just installed you can run just run to run both the collector and web services.

Connect to the server at http://localhost:8000.

Testing

There is a Justfile with some commonly used commands and tests. Run just to run the general test suite.

just pre-commit

Runs pre-commit to check/format files.

just fix

Runs Ruff to do static linting and formatting.

just mypy

Run mypy static type checker.

just test-all

Run entire test suite.

Tip

Copy sysinfo.json samples into tests/data to verify they can be successfully parsed.

just docs

Generate HTML documentation locally via Sphinx.

just make-migration

Create new database migrations via Alembic.

just migrate-db

Apply Alembic database migrations.

Architecture

Organization

Repository organization (and significant files)

alembic/    # database migrations/setup
docs/       # documentation in Sphinx/reStructuredText
meshinfo/
  models/       # SQLAlchemy database models
  static/       # static resources for the web site
  templates/    # Jinja2 templates for HTML rendering
  tests/        # pytest tests
  views/        # Pyramid view functions
                # (provide the data that is passed to the templates)
  aredn.py      # AREDN node parsing functionality
  backup.py     # import/export tools
  cli.py        # command line entry points
  collector.py  # collects info and saves it
  config.py     # application configuration
  historical.py # saving and graphing historical data points
  poller.py     # polls the network
  report.py     # simple network report
  routes.py     # defines URL routes for Pyramid

Tools

Mesh Info leverages the following Python frameworks/libraries:

The following frontend libraries/tools are vendored in this repository (because the goal is that clients do not need internet access to use the tool):