.. _ref-gis-install:

======================

GeoDjango Installation

======================

Overview

========

In general, GeoDjango installation requires:

1. :ref:`python24` and :ref:`django`

2. :ref:`spatial_database`

3. :ref:`geospatial_libs`

Details for each of the requirements and installation instructions

are provided in the sections below.   In addition, platform-specific

instructions are available for:

* :ref:`macosx`

* :ref:`ubuntudebian`

* :ref:`windows`

.. admonition:: Use the Source

    Because GeoDjango takes advantage of the latest in the open source geospatial

    software technology, recent versions of the libraries are necessary.

    If binary packages aren't available for your platform,

    :ref:`installation from source <build_from_source>`

    may be required. When compiling the libraries from source, please follow the

    directions closely, especially if you're a beginner.

Requirements

============

.. _python24:

Python 2.4+

-----------

Python 2.4 is the minimum version supported by Django, however Python 2.5+ is

recommended because the `ctypes`__ module comes included; otherwise, 2.4 users

will need to `download and install ctypes`__.

__ http://docs.python.org/lib/module-ctypes.html

__ http://sourceforge.net/projects/ctypes/files/

.. _django:

Django

------

Because GeoDjango is included with Django, please refer to Django's

:doc:`installation instructions </intro/install>` for details on how to install.

.. _spatial_database:

Spatial Database

----------------

PostgreSQL (with PostGIS), MySQL, Oracle, and SQLite (with SpatiaLite) are

the spatial databases currently supported.

.. note::

    PostGIS is recommended, because it is the most mature and feature-rich

    open source spatial database.

The geospatial libraries required for a GeoDjango installation depends

on the spatial database used.  The following lists the library requirements,

supported versions, and any notes for each of the supported database backends:

==================  ==============================  ==================  ==========================================================

Database            Library Requirements            Supported Versions  Notes

==================  ==============================  ==================  ==========================================================

PostgreSQL          GEOS, PROJ.4, PostGIS           8.1+                Requires PostGIS.

MySQL               GEOS                            5.x                 Not OGC-compliant; limited functionality.

Oracle              GEOS                            10.2, 11            XE not supported; not tested with 9.

SQLite              GEOS, GDAL, PROJ.4, SpatiaLite  3.6.+               Requires SpatiaLite 2.3+, pysqlite2 2.5+, and Django 1.1.

==================  ==============================  ==================  ==========================================================

.. _geospatial_libs:

Geospatial Libraries

--------------------

GeoDjango uses and/or provides interfaces for the the following open source

geospatial libraries:

========================  ====================================  ================================  ==========================

Program                   Description                           Required                          Supported Versions

========================  ====================================  ================================  ==========================

:ref:`GEOS <ref-geos>`    Geometry Engine Open Source           Yes                               3.2, 3.1, 3.0

`PROJ.4`_                 Cartographic Projections library      Yes (PostgreSQL and SQLite only)  4.7, 4.6, 4.5, 4.4

:ref:`GDAL <ref-gdal>`    Geospatial Data Abstraction Library   No (but, required for SQLite)     1.7, 1.6, 1.5, 1.4

:ref:`GeoIP <ref-geoip>`  IP-based geolocation library          No                                1.4

`PostGIS`__               Spatial extensions for PostgreSQL     Yes (PostgreSQL only)             1.5, 1.4, 1.3

`SpatiaLite`__            Spatial extensions for SQLite         Yes (SQLite only)                 2.4, 2.3

========================  ====================================  ================================  ==========================

.. admonition::  Install GDAL

    While :ref:`gdalbuild` is technically not required, it is *recommended*.

    Some features of GeoDjango (including the :ref:`ref-layermapping` and the geographic

    admin) depend on its functionality.

.. note::

    The GeoDjango interfaces to GEOS, GDAL, and GeoIP may be used

    independently of Django.  In other words, no database or settings file

    required -- just import them as normal from :mod:`django.contrib.gis`.

.. _PROJ.4: http://trac.osgeo.org/proj/

__ http://postgis.refractions.net/

__ http://www.gaia-gis.it/spatialite/index.html

.. _build_from_source:

Building from Source

====================

When installing from source on UNIX and GNU/Linux systems, please follow

the installation instructions carefully, and install the libraries in the

given order.  If using MySQL or Oracle as the spatial database, only GEOS

is required.

.. note::

   On Linux platforms, it may be necessarry to run the ``ldconfig``

   command after installing each library.  For example::

       $ sudo make install

       $ sudo ldconfig

.. note::

    OS X users are required to install `Apple Developer Tools`_ in order

    to compile software from source.  This is typically included on your

    OS X installation DVDs.

.. _Apple Developer Tools: http://developer.apple.com/tools/xcode/

.. _geosbuild:

GEOS

----

GEOS is a C++ library for performing geometric operations, and is the default

internal geometry representation used by GeoDjango (it's behind the "lazy"

geometries).  Specifically, the C API library is called (e.g., ``libgeos_c.so``)

directly from Python using ctypes.

First, download GEOS 3.2 from the refractions Web site and untar the source

archive::

    $ wget http://download.osgeo.org/geos/geos-3.2.2.tar.bz2

    $ tar xjf geos-3.2.2.tar.bz2

Next, change into the directory where GEOS was unpacked, run the configure

script, compile, and install::

    $ cd geos-3.2.2

    $ ./configure

    $ make

    $ sudo make install

    $ cd ..

Troubleshooting

^^^^^^^^^^^^^^^

Can't find GEOS Library

~~~~~~~~~~~~~~~~~~~~~~~

When GeoDjango can't find GEOS, this error is raised::

    ImportError: Could not find the GEOS library (tried "geos_c"). Try setting GEOS_LIBRARY_PATH in your settings.

The most common solution is to properly configure your :ref:`libsettings` *or* set

:ref:`geoslibrarypath` in your settings.

If using a binary package of GEOS (e.g., on Ubuntu 8.10), you may need to :ref:`binutils`.

.. _geoslibrarypath:

``GEOS_LIBRARY_PATH``

~~~~~~~~~~~~~~~~~~~~~

If your GEOS library is in a non-standard location, or you don't want to

modify the system's library path then the :setting:`GEOS_LIBRARY_PATH`  setting

may be added to your Django settings file with the full path to the GEOS

C library.  For example::

    GEOS_LIBRARY_PATH = '/home/bob/local/lib/libgeos_c.so'

.. note::

    The setting must be the *full* path to the **C** shared library; in

    other words you want to use ``libgeos_c.so``, not ``libgeos.so``.

.. _proj4:

PROJ.4

------

`PROJ.4`_ is a library for converting geospatial data to different coordinate

reference systems.

First, download the PROJ.4 source code and datum shifting files [#]_::

    $ wget http://download.osgeo.org/proj/proj-4.7.0.tar.gz

    $ wget http://download.osgeo.org/proj/proj-datumgrid-1.5.zip

Next, untar the source code archive, and extract the datum shifting files in the

``nad`` subdirectory.  This must be done *prior* to configuration::

    $ tar xzf proj-4.7.0.tar.gz

    $ cd proj-4.7.0/nad

    $ unzip ../../proj-datumgrid-1.5.zip

    $ cd ..

Finally, configure, make and install PROJ.4::

    $ ./configure

    $ make

    $ sudo make install

    $ cd ..

.. _postgis:

PostGIS

-------

`PostGIS`__ adds geographic object support to PostgreSQL, turning it

into a spatial database. :ref:`geosbuild` and :ref:`proj4` should be

installed prior to building PostGIS.

.. note::

    The `psycopg2`_ module is required for use as the database adaptor

    when using GeoDjango with PostGIS.

.. _psycopg2: http://initd.org/projects/psycopg2

First download the source archive, and extract::

    $ wget http://postgis.refractions.net/download/postgis-1.5.2.tar.gz

    $ tar xzf postgis-1.5.2.tar.gz

    $ cd postgis-1.5.2

Next, configure, make and install PostGIS::

    $ ./configure

Finally, make and install::

    $ make

    $ sudo make install

    $ cd ..

.. note::

    GeoDjango does not automatically create a spatial database.  Please

    consult the section on :ref:`spatialdb_template` for more information.

__ http://postgis.refractions.net/

.. _gdalbuild:

GDAL

----

`GDAL`__ is an excellent open source geospatial library that has support for

reading most vector and raster spatial data formats.  Currently, GeoDjango only

supports :ref:`GDAL's vector data <ref-gdal>` capabilities [#]_.

:ref:`geosbuild` and :ref:`proj4` should be installed prior to building GDAL.

First download the latest GDAL release version and untar the archive::

    $ wget http://download.osgeo.org/gdal/gdal-1.7.2.tar.gz

    $ tar xzf gdal-1.7.2.tar.gz

    $ cd gdal-1.7.2

Configure, make and install::

    $ ./configure

    $ make # Go get some coffee, this takes a while.

    $ sudo make install

    $ cd ..

.. note::

   Because GeoDjango has it's own Python interface, the preceding instructions

   do not build GDAL's own Python bindings.  The bindings may be built by

   adding the ``--with-python`` flag when running ``configure``.  See

   `GDAL/OGR In Python`__ for more information on GDAL's bindings.

If you have any problems, please see the troubleshooting section below for

suggestions and solutions.

__ http://trac.osgeo.org/gdal/

__ http://trac.osgeo.org/gdal/wiki/GdalOgrInPython

.. _gdaltrouble:

Troubleshooting

^^^^^^^^^^^^^^^

Can't find GDAL Library

~~~~~~~~~~~~~~~~~~~~~~~

When GeoDjango can't find the GDAL library, the ``HAS_GDAL`` flag

will be false::

    >>> from django.contrib.gis import gdal

    >>> gdal.HAS_GDAL

    False

The solution is to properly configure your :ref:`libsettings` *or* set

:ref:`gdallibrarypath` in your settings.

.. _gdallibrarypath:

``GDAL_LIBRARY_PATH``

~~~~~~~~~~~~~~~~~~~~~

If your GDAL library is in a non-standard location, or you don't want to

modify the system's library path then the :setting:`GDAL_LIBRARY_PATH`

setting may be added to your Django settings file with the full path to

the GDAL library.  For example::

    GDAL_LIBRARY_PATH = '/home/sue/local/lib/libgdal.so'

.. _gdaldata:

Can't find GDAL data files (``GDAL_DATA``)

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When installed from source, GDAL versions 1.5.1 and below have an autoconf bug

that places data in the wrong location. [#]_   This can lead to error messages

like this::

    ERROR 4: Unable to open EPSG support file gcs.csv.

    ...

    OGRException: OGR failure.

The solution is to set the ``GDAL_DATA`` environment variable to the location of the

GDAL data files before invoking Python  (typically ``/usr/local/share``; use

``gdal-config --datadir`` to find out). For example::

    $ export GDAL_DATA=`gdal-config --datadir`

    $ python manage.py shell

If using Apache, you may need to add this environment variable to your configuration

file::

    SetEnv GDAL_DATA /usr/local/share

.. _spatialite:

SpatiaLite

----------

.. versionadded:: 1.1

.. note::

   Mac OS X users should follow the instructions in the :ref:`kyngchaos` section,

   as it is much easier than building from source.

`SpatiaLite`__ adds spatial support to SQLite, turning it into a full-featured

spatial database.  Because SpatiaLite has special requirements, it typically

requires SQLite and pysqlite2 (the Python SQLite DB-API adaptor) to be built from

source.  :ref:`geosbuild` and :ref:`proj4` should be installed prior to building

SpatiaLite.

After installation is complete, don't forget to read the post-installation

docs on :ref:`create_spatialite_db`.

__ http://www.gaia-gis.it/spatialite/index.html

.. _sqlite:

SQLite

^^^^^^

Typically, SQLite packages are not compiled to include the `R*Tree module`__ --

thus it must be compiled from source.  First download the latest amalgamation

source archive from the `SQLite download page`__, and extract::

    $ wget http://sqlite.org/sqlite-amalgamation-3.6.23.1.tar.gz

    $ tar xzf sqlite-amalgamation-3.6.23.1.tar.gz

    $ cd sqlite-3.6.23.1

Next, run the ``configure`` script -- however the ``CFLAGS`` environment variable

needs to be customized so that SQLite knows to build the R*Tree module::

    $ CFLAGS="-DSQLITE_ENABLE_RTREE=1" ./configure

    $ make

    $ sudo make install

    $ cd ..

.. note::

    If using Ubuntu, installing a newer SQLite from source can be very difficult

    because it links to the existing ``libsqlite3.so`` in ``/usr/lib`` which

    many other packages depend on.  Unfortunately, the best solution at this time

    is to overwrite the existing library by adding ``--prefix=/usr`` to the

    ``configure`` command.

__ http://www.sqlite.org/rtree.html

__ http://www.sqlite.org/download.html

.. _spatialitebuild :

SpatiaLite Library (``libspatialite``) and Tools (``spatialite``)

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

After SQLite has been built with the R*Tree module enabled, get the latest

SpatiaLite library source and tools bundle from the `download page`__::

    $ wget http://www.gaia-gis.it/spatialite/libspatialite-amalgamation-2.3.1.tar.gz

    $ wget http://www.gaia-gis.it/spatialite/spatialite-tools-2.3.1.tar.gz

    $ tar xzf libspatialite-amalgamation-2.3.1.tar.gz

    $ tar xzf spatialite-tools-2.3.1.tar.gz

Prior to attempting to build, please read the important notes below to see if

customization of the ``configure`` command is necessary.  If not, then run the

``configure`` script, make, and install for the SpatiaLite library::

    $ cd libspatialite-amalgamation-2.3.1

    $ ./configure # May need to modified, see notes below.

    $ make

    $ sudo make install

    $ cd ..

Finally, do the same for the SpatiaLite tools::

    $ cd spatialite-tools-2.3.1

    $ ./configure # May need to modified, see notes below.

    $ make

    $ sudo make install

    $ cd ..

.. note::

    If you've installed GEOS and PROJ.4 from binary packages, you will have to specify

    their paths when running the ``configure`` scripts for *both* the library and the

    tools (the configure scripts look, by default, in ``/usr/local``).  For example,

    on Debian/Ubuntu distributions that have GEOS and PROJ.4 packages, the command would be::

       $ ./configure --with-proj-include=/usr/include --with-proj-lib=/usr/lib --with-geos-include=/usr/include --with-geos-lib=/usr/lib

.. note::

    For Mac OS X users building from source, the SpatiaLite library *and* tools

    need to have their ``target`` configured::

        $ ./configure --target=macosx

__ http://www.gaia-gis.it/spatialite/sources.html

.. _pysqlite2:

pysqlite2

^^^^^^^^^

Because SpatiaLite must be loaded as an external extension, it requires the

``enable_load_extension`` method, which is only available in versions 2.5+.

Thus, download pysqlite2 2.6, and untar::

    $ wget http://pysqlite.googlecode.com/files/pysqlite-2.6.0.tar.gz

    $ tar xzf pysqlite-2.6.0.tar.gz

    $ cd pysqlite-2.6.0

Next, use a text editor (e.g., ``emacs`` or ``vi``) to edit the ``setup.cfg`` file

to look like the following::

    [build_ext]

    #define=

    include_dirs=/usr/local/include

    library_dirs=/usr/local/lib

    libraries=sqlite3

    #define=SQLITE_OMIT_LOAD_EXTENSION

.. note::

    The important thing here is to make sure you comment out the the

    ``define=SQLITE_OMIT_LOAD_EXTENSION`` flag and that the ``include_dirs``

    and ``library_dirs`` settings are uncommented and set to the appropriate

    path if the SQLite header files and libraries are not in ``/usr/include``

    and ``/usr/lib``, respectively.

After modifying ``setup.cfg`` appropriately, then run the ``setup.py`` script

to build and install::

    $ sudo python setup.py install

Post-Installation

=================

.. _spatialdb_template:

Creating a Spatial Database Template for PostGIS

------------------------------------------------

Creating a spatial database with PostGIS is different than normal because

additional SQL must be loaded to enable spatial functionality.  Because of

the steps in this process, it's better to create a database template that

can be reused later.

First, you need to be able to execute the commands as a privileged database

user.  For example, you can use the following to become the ``postgres`` user::

    $ sudo su - postgres

.. note::

   The location *and* name of the PostGIS SQL files (e.g., from

   ``POSTGIS_SQL_PATH`` below) depends on the version of PostGIS.

   PostGIS versions 1.3 and below use ``<pg_sharedir>/contrib/lwpostgis.sql``;

   whereas version 1.4 uses ``<sharedir>/contrib/postgis.sql`` and

   version 1.5 uses ``<sharedir>/contrib/postgis-1.5/postgis.sql``.

   The example below assumes PostGIS 1.5, thus you may need to modify

   ``POSTGIS_SQL_PATH`` and the name of the SQL file for the specific

   version of PostGIS you are using.

Once you're a database super user, then you may execute the following commands

to create a PostGIS spatial database template.  If running Ubuntu :ref:`ibex`

or Debian :ref:`lenny`, please refer to their specific documentation for

modifications to these commands::

    $ POSTGIS_SQL_PATH=`pg_config --sharedir`/contrib/postgis-1.5