Nodeshot

Introduction

Nodeshot is an easy to use Wireless Community MapServer made by the Ninux Community. One instance can be find on their website. It's based on Django. This page aims at providing a tutorial on how to install an instance of this software and some additional resources and information.

Code

The code is on github: https://github.com/ninuxorg/nodeshot

Mailing List

Join the mailing list if you use it or have questions: http://ml.ninux.org/mailman/listinfo/nodeshot

Requirements

Before starting the installation be sure to have a server ready with the following software:

• Linux OS

• Python > 2.5

• Django > 1.4 (GenericIPAddressField for IPV6 was added in 1.4)

• Web server (eg: apache, nginx), alternatively you can use the django development server (for development only)
• Database (mysql, postgresql, sqlite3 and others, see setting.example.py)

Installing Django

Installing django is out of the scope of this document, for that please check the official django documentation: https://docs.djangoproject.com/en/1.4/intro/install/ . We advise to install the latest development version from svn or git so it's easy to upgrade.

In a production environment you must setup a VIRTUAL HOST in your webserver and to enable MOD_PYTHON or MOD_WSGI in order to get Nodeshot to work. That's also out of the scope of this guide because the way you want to do that might vary depending on distribution, habits, ecc.

if you use Apache + mod_wsgi this is the code you need to get it to work (create a file called wsgi.py):

vim wsgi.py

paste this code:

path = '/path/to/nodeshot-folder/'  # edit this line according to your configuration

import os
import sys

sys.path.append(path)
os.environ['DJANGO_SETTINGS_MODULE'] = 'settings'

import django.core.handlers.wsgi
application = django.core.handlers.wsgi.WSGIHandler()

then in your apache virtual host configuration you need to add:

WSGIScriptAlias / /path/to/nodeshot-folder/wsgi.py

Where do I place the code?

Django applications are not PHP code, they don't need to be put in the public folder of the virtualhost. Infact it is better to store them in a folder which is not accessible from HTTP.

An example of common structure is the following:

  # media files (javascript, css, ecc)
  /var/www/mapserver/public_html
      ./media
          ./css
          ./js
          ./images
  # django code
  /var/www/mapserver/code/
       settings.py
       .. eccetera ..

Install nodeshot

1. Choose the folder where you want to store the code of the project and clone the git repository with: git clone https://github.com/ninuxorg/nodeshot.git

2. On some systems it might be necessary to rename the folder created by git with a different name than "nodeshot" (eg: mapserver) because otherwise python might not be able to distinguish between the real python application and the container folder.

$ mv nodeshot mapserver

More info about this issue here: https://github.com/ninuxorg/nodeshot/issues/85

3. Create the database for nodeshot

if using mysql or postgresql create a new database in the web admin tool or via command line

MySQL: Set up a database for MySQL for the root user and a password e.g. "Nodeshotpassword"

mysql -u root -p Nodeshotpassword

Sqlite3: doesn't need you to create anydatabase, indicate the absolute path were you want django to create the file for example "/home/USER/mapserver/nodeshot.db"

4. Install python dependencies

pip install -r requirements.txt

5. Collect static files

./manage.py collectstatic 

6. Then edit the settings of nodeshot in the nodeshot folder.

a) Create settings.py by copying settings.example.py with the following command:

$ cp settings.example.py settings.py

b) Edit the settings file following the instructions in the comments and according to your needs

c) Fill in the following database settings correctly

set TIME_ZONE to your area
set LANGUAGE_CODE to your language
set SITE_URL to your URL (localhost if in development environment)
set NODESHOT_GMAP_CENTER, change the coordinates of the center of the map to your area
set NODESHOT_SITE (name and domain)
edit NODESHOT_KML['description'] to a description that suits your community (optional)
edit NODESHOT_ROUTING_PROTOCOLS and choose the ones that are used in your network
set NODESHOT_DEFAULT_ROUTING_PROTOCOL to the prefered choice

NODESHOT_FRONTEND_SETTINGS:

META_ROBOTS: this indicates if you want Google to index your map-server or not. Possible choices are the ones indicated here http://googlewebmastercentral.blogspot.com/2007/03/using-robots-meta-tag.html

SHOW_STATISTICS: boolean that indicates if you want to show the number of active nodes, potential nodes, hotspots, links and total link surface on the website

SHOW_KML_LINK: this indicates if you want to show the KML feed icon and link

HELP_URL: set up an URL on your website to explain how to use the map-server or whatever you need to tell to your users (this might change in the future, maybe is better to ship some instrctions with the core code)

6. create the database structure

$ python manage.py syncdb

this command creates the necessary SQL tables.

7. the previous command might fails if you miss some python libraries. If this happens you must install these libraries in order to proceed.

Some common missing libraries are:

* MySQLdb - fix with "apt-get install python-mysqldb" (depends on your distribution)

Media files

If you use apache you must link the folder that contains the static files (css, images, js) in your apache public folder. Example:

$ ln -s /home/user/you/mapserver/nodeshot/media /var/www/mapserver/public_html/media

TODO: might miss some cases

Admin media files

If you go to <YOUR_URL>/admin/ you will notice that the static files (css, images and javascript) for the admin interface are missing. Infact those files are stored in the django framework. You can either copy or link those files, but we strongly advise to use a symbolic link because when you will update django to a newer version the static admin files will also get updated automatically.

Example:

ln -s <DJANGO-INSTALLATION-DIR>/contrib/admin/static/admin <PUBLIC-DIR>/media/admin

Substitute <DJANGO-INSTALLATION-DIR> with the path to the directory where django is installed and <PUBLIC-DIR> with the path to the directory of your server which is reachable from public HTTP.

Troubleshooting

If you get errors for missing libraries you will need to install them. You can install python libraries either with your package manager or with easy_install / pip_install. This depends on your linux distribution.

If the admin interface in {PROJECT_URL}/admin is not working, try to run this command from the working directory of the code:

sudo chown www-data. .

Setup the Cronjobs

There are two cronjobs to setup for nodeshot:

1. nodeshot/scripts/read_topology_hna.py
2. nodeshot/scripts/snmp.py

There is one problem though: these scripts have been written for the ninux network and might not work for your network or need additional work. You could either make new scripts that suits your network or you could help us in improving the actual scripts in order to make them work both on our network and yours. The choice is up to you, the important thing is that there's somebody in your network who is able to program in python and can help out.

Communities using nodeshot

• Ninux: http://map.ninux.org/

• Seattle Meshnet: https://seattlemeshnet-nodeshot.appspot.com/

• Sudoroom mesh (Oakland, California): http://meshmap.sudoroom.org/