.\" Man page generated from reStructeredText.
.TH featureserver  "2007-12-31" "1.11" "GIS Utilities"
.SH NAME
featureserver \- Simple Python geographic feature server

.SH DESCRIPTION
FeatureServer is a simple Python\-based geographic feature server. It allows
you to store geogrpahic vector features in a number of different backends,
and interact with them \-\- creating, updating, and deleting \-\- via a
REST\-based API.

FeatureServer will run under Python CGI, mod_python, or as a standalone server.

FeatureServer was designed as a companion to OpenLayers, the BSD licensed web
mapping interface. For help with setting up FeatureServer for use with
OpenLayers, please feel free to stop by #featureserver, on irc.freenode.net, or
to send email to featureserver@featureserver.org.

FeatureServer is released under an open source license similar to the BSD
license.

.SH RUNNING UNDER CGI

.TP 2
\(bu
FeatureServer should have a CGI installed under /usr/lib/cgi-bin,
called featureserver.cgi. This is accessible from 
http://yourmachine.example.com/cgi-bin/featureserver.cgi 

.TP 2
\(bu
Edit featureserver.cfg to point the \'file\' attribute of the \'scribble\'
datasource to the location you wish to save your database.

.TP 2
\(bu
Visit:

.nf
http://yourmachine.example.com/yourdir/featureserver.cgi/scribble/all.atom
.fi

.TP 2
\(bu
If you see an empty GeoRSS feed, you have set up your configuration
correctly. Congrats!


.SH RUNNING UNDER MOD_PYTHON

.TP 2
\(bu
Add the following to your Apache configuration, under a <Directory> heading:


.nf
AddHandler python\-program .py
PythonPath sys.path+[\'/path/to/featureserver/FeatureServer\', \'/path/to/featureserver\']
PythonHandler FeatureServer.Server
PythonOption FeatureServerConfig /path/to/featureserver.cfg
.fi

.TP 2
\(bu
An example might look like:


.nf
<Directory /var/www/featureserver/>
    AddHandler python\-program .py
    PythonPath sys.path+[\'/var/www/featureserver/FeatureServer\', \'/var/www/featureserver\']
    PythonHandler FeatureServer.Server
    PythonOption FeatureServerConfig /var/www/featureserver/featureserver.cfg
</Directory>
.fi

.TP 2
\(bu
In this example, /var/www/featureserver is the directory resulting from
the code extraction.


.TP 2
\(bu
Visit:
http://yourmachine.example.com/featureserver/featureserver.py/scribble/all.atom

.TP 2
\(bu
If you see an empty GeoRSS file you have set up your configuration correctly.
Congrats!


.TP 2
\(bu
Note that mod_python has not yet been well tested, and may not work well
for all data sources.


.SH RUNNING STANDALONE (UNDER WSGI)
FeatureServer comes with a standalone HTTP server which uses the WSGI handler.
This implementation depends on 
.I Python Paste
, which can be installed via the python-paste package.

.\" depart_block_quote
For versions of Python earlier than 2.5, you will also need to install
wsgiref, which is provided by the python-wsgiref package.

.\" depart_block_quote
Once you have all the prerequisites installed, simply run:


.\" visit_block_quote

.nf
featureserver_http_server
.fi

.\" depart_block_quote
This will start a webserver listening on port 8080, after which you should
be able to open:


.\" visit_block_quote

.nf
http://yourmachine.example.com:8080/scribble/all.atom
.fi

.\" depart_block_quote
to see your first file.


.SH RUNNING UNDER FASTCGI
FeatureServer comes with a fastcgi implementation. In order to use this
implementation, you will need to install flup, available via the python-flup
package.



.\" depart_block_quote
This implementation also depends on Python Paste, which can be installed via
the python-paste package. 


.\" depart_block_quote
Once you have done this, you can configure your fastcgi server to use
featureserver.fcgi.

Configuring FastCGI is beyond the scope of this documentation.


.SH CONFIGURATION
FeatureServer is configured by a config file, defaulting to
/etc/featureserver.cfg.  FeatureServer data source documentation is available
in /usr/share/doc/featureserver/DataSources.txt.


.SH USING FEATURESERVER WITH OPENLAYERS
To run OpenLayers with FeatureServer, the URL passed to the
OpenLayers.Layer.WFS constructor must point to the FeatureServer script,
i.e. featureserver.cgi or featureserver.py. As an example see the
index.html file included in /usr/share/doc/featureserver/examples/.

Note: index.html assumes FeatureServer is set up under CGI (see above).
If you set up FeatureServer under mod_python you\'d need to slighly
modify index.html: the URL passed to the OpenLayers.Layer.WFS constructor
must point to the mod_python script as opposed to the CGI script, so replace
featureserver.cgi with featureserver.py. Similarly, you would need to edit
this URL if you were to use FeatureServer with the standalone HTTP Server
or FastCGI.


.SH SEE ALSO
http://featureserver.org/

http://openlayers.org/


.SH AUTHOR
crschmidt@metacarta.com

.SH COPYRIGHT
2006-2007 MetaCarta, Inc.