root/primagis.buildout/branches/zc.buildout/README.txt

===================
PrimaGIS - Buildout
===================

This is a buildout system for PrimaGIS -- a web mapping solution for
Plone. Its main purpose is to provide a dependable and repeatable way
for developers to easily setup a development environment that contains
all the dependencies and allows for easy development.

Although the focus of the buildout is developers the end result of the
buildout is a working software setup that may also be used in
production.

The buildout provides an isolated sandbox environment for using and
developing PrimaGIS without interfering with the rest of your system.

The buildout is implemented using zc.buildout_

_zc.buildout: http://pypi.python.org/pypi/zc.buildout

=================
Table of Contents
=================
1.Quickstart
2.Bootstrapping the buildout 
3.Buildout structure
4.Setting up PostgreSQL
5.Developing PrimaGIS
6.OSX Notes
7.Building on Debian based systems(see README-deb.txt)
=================

Quickstart
----------

The following commands will install the whole of PrimaGIS and setup a
PostgreSQL db for testing For detailed instructions read below.

Do not run any of the following commands as root. Run as a normal user or
problems will result when attempting to start PostGreSQL and Zope.

1. Get the buildout from the SVN repository and bootstrap it. Note
   that you will need a python version >= 2.4 (but < 2.5) to run the
   buildout.

   $ svn co http://svn.gispython.org/svn/zope/primagis.buildout/branches/zc.buildout primagis.buildout
   $ cd primagis.buildout
   $ python bootstrap.py

2. Execute the buildout. The buildout will download, compile and
   install a fairly large number of software components and may take a
   while (~2 hours). Be patient.

   $ ./bin/buildout

   If the network connection is lost during the buildout and the buildout
   stops, run the buildout again. The buildout will start again from the last
   incomplete step, saving significant time.

3. Set up the PostgreSQL database (optional).

   If a port for the PostgreSQL server is not specified, the default is 5432.
   Insure the port does not collide with any other instances.

   $ ./bin/python init_postgresql.py [--port=xxxx]

   This step may be run over again many times to re-initialize the sample data
   in PostGreSQL. But running the re-initialization will delete all data
   previously saved in the database.

4. Insure PostGreSQL is running.

   To see if the PostGreSQL server is running:

   $ .bin/pg_ctl status

   If the PostGresQL server is not running, start it:

   $ ./bin/pg_ctl start

   If the process appears to hang after the "database system is ready" message,
   simply hit the enter key to return to the command prompt.

5. Enable the ZCML configuration.

   Make copies of the ZCML templates in ./src/ZCO/src/zco/mapconfiguration:

   datastores.zcml.dist
   maprenderer.zcml.dist
   symbolizers.zcml.dist

   by removing the .dist file extension:

   $ cd src/ZCO/src/zco/mapconfiguration
   $ for f in *.dist; do cp -p "$f" "${f%?????}"; done
   $ cd -

6. Enable the font set in ZCML.

   PCL needs to know about some fonts. Tell Zope about the font by editing:

   ./src/ZCO/src/zco/mapconfiguration/maprenderer.zcml

   Find the <gis:mapserverRenderer> tag and edit its fontset attribute. The
   fontset to which to point the attribute is:

   ./base/pcl.buildout/src/PCL/examples/fonts.txt
   
   The attribute expects an absolute path. So replace the . with the path
   to your buildout.

7. Enable the PostGIS datastore in ZCML.

   PCL needs to know where to get data. Tell Zope about PostGIS by editing:

   ./src/ZCO/src/zco/mapconfiguration/datastores.zcml

   Find the <gis:postgisDataStore> tag. Uncomment it. Edit its dns attribute
   by removing the user and password keyword/value pairs.

8. Enable the map symbolizers in ZCML.

   ZCO needs to know about a number of symbolizers. Tell Zope about the
   symbolizers by editing:

   ./src/ZCO/src/zco/mapconfiguration/symbolizers.zcml

   Uncomment:

   a. the pointSymbolizer with the name attribute of "circle."
   b. the lineSymbolizer
   c. the polygonSymbolizer
   d. the textSymbolizer

9. Run the test cases.

   The really important test is:

   $ ./bin/zope-instance test -s primagis

   Other tests of individual dependencies are scripts in ./bin. It is not
   unusual to see some failures in edge cases for dependecies. The important
   test is running the PrimaGIS unit tests in the Zope instance as shown above.

10. Start Zope

   Use:

   $ ./bin/zope-instance fg

   the first time in order to observe the start up messages for errors. For
   subsequent starts of Zope, use:

   $ ./bin/zope-instance start

11. Browse the ZMI.

   Point a browser at the default for the buildout:

   http://localhost:7000/manage

   The userid and password for the buildout are both "admin."

12. Create a Plone Site.

   In the root of the ZMI, add a Plone Site. It is not necessary to select any
   extension profiles.

13. Install the PrimaGIS product in Plone.

   View the Plone Site just created. Go to Site Setup -> Add-on Products.
   Select PrimaGIS and click "Install." View the install log to see that the
   install was successful.

14. Create a Map.

   In the root of the Plone Site, add a new Map item. Call it something like
   "World."After saving, click on the "Configure Map" tab, change the Map Units
   to Decimal Degrees, and click Apply.

15. Create a Layer.

   A Map is a folderish item. It contains Map Layers of various stripes. First,
   add a Layer item to the Map. Call this Layer something like "World Borders."

   After saving, click on the "Configure Layer" tab. Select "teststore"
   (previously enabled in datasource.zcml) as the Spatial Data Source and
   postgis.world_borders as the feature set within that data source.
   Click Apply.

   After configuring the Layer, click on the "Manage Styles" tab. Add a new
   rule to the Layer. The only required fields are the Title and a Symbolizer.
   Call it something like "Borders." Select blueGreenPolygon for a Symbolizer
   (previously enabled in symbolizers.zcml). Click Save.

16. Create a Presentation Layer. 

   Return to the View of the Map item. Add a Presentation Layer to the Map.
   Call it something like "Boundaries," select the Layer you previously added
   to the Map and "Base layer" as the Layer type. Click Save.

17. View the Map.

   Return to the View of the Map item. Select "OpenLayers" from the Display
   content action drop down menu. You should now see a map.

   If you see "an error occurred" on the map display, try zooming in on the
   map. PrimaGIS uses Zope RAM caching. A previous error in your Map item
   or any of the items it contains may be cached. Otherwise, the logs for the
   Zope instance are in ./var/log.

Bootstrapping the buildout
--------------------------

When the buildout is checked out from the repository it needs to be
bootstrapped before it is ready to use. Simply run::

  $ python bootstrap.py

in the root of the buildout to get everything ready for work. You will
need to use a Python version >= 2.4. This will not run the buildout,
but will set the necessary scripts in the right places for doing it.

After the bootstrapping you will have the buildout script in::

  ./bin/buildout

which is used to run the actual buildout process. For a full listing
of available options see::

  ./bin/buildout --help


Buildout structure
-------------------

PrimaGIS buildout builds on top of other buildouts defined for some of
the dependencies, namely other projects from the GIS-Python Laboratory
(www.gispython.org). These buildouts are contained within the ``base``
directory.

The main configuration file is ``buildout.cfg`` which in turn
references the other buildouts from the ``base`` directory. You may
wish to modify the configuration to change the Zope HTTP port or other
settings.

For more information on the individual buildouts refer to their
corresponding ``README.txt`` files.



Setting up PostgreSQL
---------------------

PCL-Core contains code and tests that interacts with a PostgreSQL
database. The buildout compiles the database server automatically, but
test data must be populated with a manual step.

In the root of the buildout directory is a python script called
``init_postgresql.py`` that takes care of setting up a database for
testing PCL. You can run by simply calling::

  $ ./bin/python init_postgresql.py 

You can optionally set the port number by using the --port option. The
default port is 5432.

You can run the script as many times as you want, but be aware that it
will reset the whole database. You shouldn't use the test database to
store any important data as it will be lost on subsequent runs of the
script.

See the OSX Notes section below if you are using Mac OSX.


Developing PrimaGIS
-------------------

All the PrimaGIS components will be installed as development eggs, so
you can keep modifying the source on-the-fly. All editable source code
is located under the ``src/`` directory within the buildout.

There is also a Python interpreter script located in::

  ./bin/python

which has all the relevant components available for instant use.


OSX Notes
---------

Running the PostgreSQL database server on Mac OS X may require
modifying the amount of shared memory available on your system. See

  http://www.postgresql.org/docs/8.2/static/kernel-resources.html#SYSVIPC

for more detailed instructions.