# Neighborhood Mesh ISP

A lightweight operations toolkit for running a community-owned mesh-network ISP. It helps neighborhood operators plan nodes, provision routers, monitor links, track subscribers, and publish a local service map.

The project is designed for small volunteer networks using OpenWrt routers, directional Wi-Fi links, and optional fiber or LTE backhaul.

## Features

- Node inventory with locations, hardware models, roles, and owners
- Mesh link tracking with signal, throughput, and uptime history
- OpenWrt provisioning templates
- Subscriber and service-area management
- Prometheus-compatible metrics exporter
- Outage status page for members
- Role-based admin access for volunteers
- YAML-based configuration for simple deployments

## Install

### Requirements

- Linux server or VPS
- Docker and Docker Compose
- PostgreSQL 15+
- Node.js 20+ for local development
- OpenWrt-compatible routers for field deployment

### Docker Compose

```bash
git clone https://github.com/example/neighborhood-mesh-isp.git
cd neighborhood-mesh-isp

cp config.example.yml config.yml
cp .env.example .env

docker compose up -d
```

The web dashboard will be available at:

```text
http://localhost:8080
```

### Local Development

```bash
npm install
npm run db:migrate
npm run dev
```

## Usage

Create the first administrator account:

```bash
npm run admin:create -- --email ops@example.org
```

Add a mesh node:

```bash
npm run node:add -- \
  --name roof-12th-ave \
  --role relay \
  --lat 40.7128 \
  --lng -74.0060 \
  --hardware "MikroTik LHG XL 5"
```

Generate an OpenWrt provisioning bundle:

```bash
npm run provision -- --node roof-12th-ave --output ./build/roof-12th-ave
```

Export metrics for Prometheus:

```bash
curl http://localhost:8080/metrics
```

## Configuration

Configuration is stored in `config.yml`.

```yaml
network:
  name: Neighborhood Mesh
  domain: mesh.local
  timezone: America/New_York

dashboard:
  public_url: https://status.example.org
  session_ttl_hours: 12

database:
  url: postgres://mesh:mesh@localhost:5432/mesh_isp

monitoring:
  scrape_interval_seconds: 30
  node_timeout_seconds: 90
  prometheus_enabled: true

provisioning:
  firmware_target: openwrt-23.05
  default_ssid: neighborhood-mesh
  management_vlan: 10
  member_vlan: 20

backhaul:
  providers:
    - name: community-fiber
      type: fiber
      capacity_mbps: 1000
    - name: emergency-lte
      type: lte
      capacity_mbps: 100
```

### Important Options

| Option | Description |
| --- | --- |
| `network.name` | Display name used in the dashboard and status page |
| `network.domain` | Internal DNS suffix for mesh devices |
| `dashboard.public_url` | Public URL for members and volunteers |
| `monitoring.scrape_interval_seconds` | How often nodes are checked |
| `provisioning.default_ssid` | Default SSID used by generated router configs |
| `provisioning.management_vlan` | VLAN reserved for operator access |
| `backhaul.providers` | Upstream internet connections available to the mesh |

## Deployment Notes

- Keep management interfaces on a separate VLAN.
- Use unique device credentials per node.
- Mount outdoor radios with proper grounding and weatherproofing.
- Document roof access, power sources, and emergency contacts.
- Test failover before relying on backup backhaul.

## License

MIT