The goal of this project is to create a lightweight yet versatile Free Network mapping application.


  • federated data syncronization between AlterMap servers
  • HTTP RESTful API that will allow routers to directly report data to their AlterMap server and associated applications to freely interact with this data
  • near-realtime visualization of data as it gets updated from any data-source
  • router-side agent automatically updates information

Expected features:

  • plugins system to allow each network to implement their own custom data acquisition and display interfaces while maintaining core compatibility with other AlterMap servers
  • mobile-friendly interface


At the core of AlterMap is the non-relational database CouchDB. AlterMap itself is deployed as a CouchApp and can be served entirely form CouchDB.

The included client interface is browser based, although AletMap data data will be accessible to any application that can communicate with it's RESTful HTTP API. The browser based client relies heavily on some JavaScript libraries:

Server installation


Information on installation and configuration can be found in their respective websites; they are probably already packaged for your GNU/Linux distribution.

All libraries and files required by AlterMap are packaged as a CouchApp, so once you have installed the server dependencies, you will only need to clone the repository:

$ git clone

Copy the provided .couchapprc.example to .couchapprc and edit if needed.

And then, from within the app's folder, install the application to your CouchDB server (make sure your couchdb server is runnning):

$ erica push altermap

If you are using default configurations, you should be able to see the app running by browsing to this address:


Router Agent

The router agent: altermap-agent, is a Lua script that will send collected information about the router to the configured AlterMap server.

In OpenWRT you can install it from this repository:

Or manually download the .ipk and install it:

You can also directly check out the code and install it manually.

The package configures a cron task that runs every hour.

You can manually run the agent at any time:
# /usr/sbin/altermap-agent

Or if you wish to see the data the agent is sending to the server:

# ALTERMAP_DEBUG=1 /usr/sbin/altermap-agent

The node must exist in the AlterMap database so the router can push information. You can create and position the node through the AlterMap web interface.