'Geo' Template Overview

Introduction

The geo template is the first in a series of 'contributed' or non-core templates that are shipped as part of the Whitebeam application server.

Contributed templates tend to provide a specialist service applicable to a small subset of potential Whitebeam applications.

In the case of the 'geo' template - the service provided is to take an IP address and to return geographical data about the owner of that address. This information has a number of potential uses including targeted advertising, content selection or simply blocking certain geographies from access in localised service.

Whitebeam's service based architecture and template model make implementation of functionality like this both simple and efficient. The Geo template loads a geographical database of IP blocks into memory. As a single process the amount of memory used is negligible. The application then receives XML mapping requests, consults the database and returns the results to the caller.

The overhead of loading the database happens once when the template application is started (but can be re-started to load a newer version of the database with no loss of service).

Contrast this model with alternatives where the data must either be loaded into each process and each time a page wants information, or must be stored in an external database such as mySql or Postgres and endure the overhead of a database request for each lookup.

This template has been contributed by YellowHawk - where it was developed to enable geographical based advertising in their GadgetSpeak web-site.

A single template method takes an IP address and returns a structure containing the bounds of the containing block of IP addresses, a two letter, three letter abbreviations for the country and a human readable name for the country.

Simple example to display the source of an HTTP request :

var ipAddr = rb.page.env.RemoteAddr();
var info = rb.geo.iplookup(ipAddr);

rb.page.write("<p>You're currently in : '"+info.country+"'</p>");

Configuring the Geo template

The template needs an IP address database to run. Ip address allocations are continually changing so Whitebeam does not ship with this information. There are a number of source of this data freely available on the Internet. The one we'd recommend downloading (which is in the correct format) is available on the following address :

http://software77.net/cgi-bin/ip-country/geo-ip.pl

Download the CSV (comma separated value) format file and store it on your server. The default location will be in /var/whitebeam/conf/IpToCountry.csv, although you can store it anywhere and specify the path when you start the Geo template.

As stated - the database does change regularly. To avoid having to stop and start the template to reload a more recent database simply send a SIGHUP signal to the geo process. The new database will be reloaded at the end of the next client request.