[[TOC()]]
= !GeoDjango Installation =

!GeoDjango requires the installation of several '''open source geographic libraries''' and a database system with '''spatial extensions'''
 * Currently PostgreSQL (with PostGIS), MySQL, and Oracle (Spatial/Locator) are supported.
 * PostgreSQL is the recommended database, having the most mature and feature-rich spatial functions and operators.
 * Note: Several components of !GeoDjango '''can''' be used without a database (ie. [http://code.google.com/p/geodjango-basic-apps/wiki/GeoIPQuickStart The GeoIP utility])

This section will describe the installation process for these prerequisites.  !GeoDjango is best supported using PostgreSQL/PostGIS on Linux/UNIX platforms, but will also run on Windows (with a little more effort).  The following platforms have been confirmed to work -- feel free to add to the list:
 * Linux 
   * Debian Woody (2.4 Kernel)
   * Debian etch (2.6 Kernel)
   * Ubuntu 7.0 (2.6 Kernel)
   * Centos 5 (2.6 Kernel)
   * White Box Enterprise Linux 3.0 (2.4 Kernel)
   * openSUSE 10.2 (2.6 Kernel)
   * Archlinux (2.6 Kernel)
 * Mac OS X 
   * 10.4.10 (Tiger)
   * 10.5 (Leopard)
 * Solaris 5.11
 * Windows XP SP2

== Linux & UNIX Platforms ==

=== Python & PostgreSQL ===
 * '''Python'''
   * ''Required:'' Python 2.4 is required because of heavy use of 2.4 decorator syntax (e.g. `@property`).  
     * If using Python 2.4, the `ctypes` module needs to be installed as well.
     * Binary packages like `python2.4-ctypes` on Ubuntu/Debian may be used; however, older distributions (like Ubuntu 6.06) use old versions of ctypes that contain bugs -- in such instances, install the latest version (currently 1.0.2) which may be obtained from the [http://sourceforge.net/project/showfiles.php?group_id=71702 ctypes sourceforge project].
   * ''Recommended:'' Python 2.5 is recommended because the `ctypes` module comes included.  [http://python.org/download/releases/2.5.2/ Python 2.5.2] is the current latest.
 * '''PostgreSQL'''
   * ''Recommended:'' PostgreSQL 8.x.  If installing binary packages, please install the development package as well for headers '''required''' in PostGIS compilation.
   * We are currently developing using both v8.1-8.3 of PostgreSQL.
   * On Ubuntu Feisty and Debian etch, install `postgresql-8.x` and `postgresql-server-dev-8.x` (the development package is '''required''' for PostGIS compilation).
     * On Debian etch install the `libpq-dev` package, which includes the `pg_config` executable (also required for PostGIS compilation).
 * '''psycopg2'''
   * [http://initd.org/tracker/psycopg/wiki/PsycopgTwo psycopg2] is a Python database adapter for PostgreSQL.  Latest version is [http://initd.org/pub/software/psycopg/psycopg2-2.0.7.tar.gz 2.0.7].

=== Django ===
!GeoDjango was merged into SVN trunk as of r8219.  Follow Django's [http://www.djangoproject.com/documentation/install/#installing-the-development-version development version installation instructions].

=== GEOS ===
 * ''Required'': GEOS v3.0.0RC4 and above (''not'' compatible with the 2.x versions).
 * ''Recommended'': GEOS [http://geos.refractions.net/downloads/geos-3.0.0.tar.bz2 3.0.0] (support for the release candidate versions will be eventually deprecated due to differences in the way geometries are serialized to WKT and HEX, as well as compilation issues for OSX 10.5 -- we urge users to migrate to 3.0.0).

[http://geos.refractions.net GEOS] is an open source C++ library for performing geometric operations, and powers !GeoDjango's "lazy" geometries.

!GeoDjango has its own GEOS `ctypes` wrapper; you do ''not'' need to enable the existing GEOS Python bindings. The `ctypes` library comes standard with Python 2.5; if you run Python 2.4, `ctypes` may be [http://sourceforge.net/project/showfiles.php?group_id=71702&package_id=71318 downloaded here], and in Debian etch you may install the `python-ctypes` package.

First, download GEOS 3.0.0 from the refractions website and untar the source archive:
{{{
$ wget http://geos.refractions.net/downloads/geos-3.0.0.tar.bz2
$ tar xjf geos-3.0.0.tar.bz2
}}}

Next, change into the directory where GEOS was unpacked, run the `configure` script, compile, and install:
{{{
$ cd geos-3.0.0
$ ./configure
$ make
# make install
}}}

'''Note:''' The path to the GEOS library may be manually specified by setting `GEOS_LIBRARY_PATH` in your settings with the full path to the GEOS library (e.g., the `.so` for linux or `.dylib` file for mac).
 * You should also confirm at this time (if running linux) that the GEOS lib dir, likely `/usr/local/lib` is within `/etc/ld.so.conf`, then run:
{{{
$ ldconfig # then restart the PostgreSQL server
}}}


=== PROJ.4 ===


 * ''Required'': 4.5.0  -- this is not a strict requirement, !GeoDjango has been tested with 4.5.0, but there is no reason to believe that previous versions (e.g., 4.4.x, 4.3.x) will not work.
 * ''Recommended'': [ftp://ftp.remotesensing.org/proj/proj-4.6.0.tar.gz 4.6.0] (the current latest).

[http://trac.osgeo.org/proj/ PROJ.4] is a library for converting geospatial data to different coordinate reference systems.

First, download PROJ.4 from the remotesensing website, and untar the source archive:
{{{
$ wget http://download.osgeo.org/proj/proj-4.6.0.tar.gz
$ tar xzf proj-4.6.0.tar.gz
}}}

Next, download the PROJ.4 [ftp://ftp.remotesensing.org/proj/proj-datumgrid-1.3.tar.gz datum shifting files].  These will come in handy for coordinate transformations when other programs (like Mapserver or Mapnik) are not able to cope with EPSG transformations (I learned the hard way). Untar/unzip these in the `nad` subdirectory of the PROJ.4 source:
{{{
$ wget ftp://ftp.remotesensing.org/proj/proj-datumgrid-1.3.tar.gz
$ cd proj-4.6.0/nad
$ tar xzf ../../proj-datumgrid-1.3.tar.gz
}}}
Do this '''before''' you do the configure/make/install dance.
 * ''See'' [http://www.remotesensing.org/proj/faq.html PROJ FAQ]; ''see also'' [http://mapserver.gis.umn.edu/data2/wilma/mapserver-users/0301/msg00541.html Frank Warmerdam's reply to a Mapserver question].

Finally, configure, make and install PROJ.4 within the proj-4.6.0 directory:
{{{
$ cd ../
$ ./configure
$ make
# make install 
}}}

=== PostGIS ===
 * ''Required'':  PostGIS v1.2.1 and above.
 * ''Recommended'': [http://postgis.refractions.net PostGIS] [http://postgis.refractions.net/download/postgis-1.3.3.tar.gz v1.3.3] (this is the current [http://postgis.refractions.net/news/20080412/ latest version]).
 * Mac and Windows binaries for PostGIS can also be found on the Refractions research [http://postgis.refractions.net/download/ download site.]

For source install first download PostGIS, and untar the archive:
{{{
$ wget http://postgis.refractions.net/download/postgis-1.3.3.tar.gz
$ tar xzf postgis-1.3.3.tar.gz
$ cd postgis-1.3.3
}}}

Run the `configure` script, `make`, and install steps. 
{{{
$ ./configure
$ make
# make install
}}}
   * Note: the `flex` package maybe required for PostGIS compilation on Debian distributions and may be installed with the command: `apt-get install flex`

Next, create a role and database for your application, and allow it to access PostGIS functionality.  PostGIS SQL files are installed in the PostgreSQL share directory (`/usr/postgres/8.2/share` in the example below; use the `pg_config --sharedir` command to determine this directory on your system).
{{{
# su - postgres
$ createuser <user>
$ createdb -O <user> <db_name>
$ createlang plpgsql <db_name>
$ psql -d <db_name> -f /usr/postgres/8.2/share/lwpostgis.sql
$ psql -d <db_name> -f /usr/postgres/8.2/share/spatial_ref_sys.sql
$ psql <db_name>
<db_name>=# ALTER TABLE geometry_columns OWNER TO <user>;
<db_name>=# ALTER TABLE spatial_ref_sys OWNER TO <user>;
}}}

 * Note: if you experience errors about not finding libraries, you may need to adjust your `LD_LIBRARY_PATH` (which may be configured system-wide by editing `/etc/ld.so.conf` and running `ldconfig`)(Hint: Most of the times the libraries you are looking for are in '/usr/local/lib').  Sometimes the errors are too many and not descriptive (i.e. operation aborted), in that cases use the '-s' switch on psql to debug step by step. On Solaris platforms use the `crle` utility to configure the runtime linking environment.

Finally, update your `settings.py` to reflect the name and user for the spatially enabled database (thus far, we only plan to support the `psycopg2` backend for PostgreSQL):
{{{
DATABASE_ENGINE='postgresql_psycopg2'
DATABASE_NAME='<db_name>'
DATABASE_USER='<user>'
}}}

=== GDAL ===
 * ''Required'': GDAL versions 1.4.0 and above (!GeoDjango has not been tested with the 1.3.x series).
 * ''Recommended'': GDAL version 1.5.x and above.

[http://trac.osgeo.org/gdal/ GDAL/OGR] is an excellent open source geospatial library that support features such as coordinate transformations and reading/writing ''both'' vector (e.g., SHP) and raster (e.g., GeoTIFF) geographic data -- however, !GeoDjango does not yet support GDAL's raster capabilities.  Installation of GDAL is ''highly recommended'' because some features (e.g., a large number of `SpatialRefSys` model routines and the `LayerMapping` utility) require GDAL capabilities; however GDAL is not required for core functionality like spatial queries.
  
First, download the latest [http://trac.osgeo.org/gdal/wiki/DownloadSource GDAL] version (currently [http://download.osgeo.org/gdal/gdal-1.5.2.tar.gz 1.5.2]), and untar the archive:
{{{
$ wget http://download.osgeo.org/gdal/gdal-1.5.2.tar.gz
$ tar xzf gdal-1.5.2.tar.gz
$ cd gdal-1.5.2
}}}

Configure specifying the data directory (if installing in `/usr/local`, then use `/usr/local/share/gdal`), run `make` (use `gmake` on Solaris platforms) and install:
{{{
$ ./configure --datadir=/usr/local/share/gdal
$ make
# make install
}}}

=== GDAL Troubleshooting ===
First try:
 * Make sure `/usr/local/lib` is in `/etc/ld.so.conf`
 * Run $ ldconfig
 * Log out and back into your shell to make sure your settings have taken effect

Specifics:

Specifying the data directory at compile time avoids having to set the `GDAL_DATA` environment variable (see [http://trac.osgeo.org/gdal/ticket/2382 GDAL ticket #2382] and the troubleshooting tip below).

'''Troubleshooting:''' If you receiving the following error message when running the GDAL tests and/or working with `SpatialReference` objects:
{{{
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 (typically `/usr/local/share`; use the `gdal-config --datadir` command to find out for sure) before invoking Python. For example:
{{{
$ export GDAL_DATA=`gdal-config --datadir`
$ python manage.py shell
}}}

You may need to add this environment variable to your Apache configuration file (sites-available/default for example): 
{{{
SetEnv GDAL_DATA /usr/local/share
}}}

'''Note:''' The path to the GDAL library may be manually specified by setting `GDAL_LIBRARY_PATH` in your settings with the full path to the GDAL library (e.g., the `.so` or `.dylib` file).  

Because !GeoDjango uses a native `ctypes` API to access OGR (Vector shape library) and OSR (Spatial reference library) capabilities, there is no need configure the GDAL Python bindings.  If you still want to use the GDAL Python API for your own applications, then use the following configuration flags:
   * `--with-python`: Enables the GDAL Python bindings (all GDAL modules in `osgeo` namespace)
   * `--with-ogpython`: The "old-generation" bindings (separate modules, e.g., `ogr` and `osr`)
   * ''See generally'' [http://trac.osgeo.org/gdal/wiki/GdalOgrInPython GDAL/OGR In Python] on the GDAL trac wiki.

== Windows ==

Still a work in progress -- but it's a start for closing #4397.

'''Note:'''  The installation for the GEOS and GDAL libaries is 'hackish' right now.   A sustainable long-term solution (i.e. an installer) needs to be developed for these libraries.  

=== Introduction ===

These instructions will cover using binary packages to install !GeoDjango on Windows 2000/XP platforms.  Compiling prerequisite packages (e.g., GEOS) from source on Windows is beyond the scope of this documentation, as it assumes the use of community-built binary installers.

That said, here are some additional program recommendations that, while not required, make your Python experience in Windows less painful:

 * The Windows command-line terminal is  It's difficult to re-size and copy and paste from.  I (jbronn) find [http://sourceforge.net/project/showfiles.php?group_id=43764&package_id=36333 Console2] more convenient to use than one supplied with Windows (`cmd.exe`).  
 * [http://ipython.scipy.org/moin/FrontPage IPython] also runs on Windows, and makes life easier.
   * Latest version of IPython is [http://ipython.scipy.org/dist/ipython-0.8.1.win32.exe 0.8.1].
   * For terminal colors and tab completion (two of IPython's strong points), also install the [http://ipython.scipy.org/moin/PyReadline/Intro pyreadline] library (latest version is [http://ipython.scipy.org/dist/pyreadline-1.4.4.win32.exe 1.4.4]).
   * For documentation, check out the [http://ipython.scipy.org/moin/IpythonOnWindows IPython on Windows] documentation.  ''See also'' [http://ipython.scipy.org/doc/manual/node2.html#sub:Under-Windows IPython installation windows instructions], and [http://ipython.scipy.org/moin/IpythonOnConsole IPython on Console].

=== Python ===

Download and run the [http://python.org/ftp/python/2.5.2/python-2.5.2.msi Python installer].  We highly recommend you use Python 2.5 or greater (2.5.2 is the latest, and the version linked to).  Python 2.5 includes the `ctypes` library, which is required for the GEOS, GDAL, and readline (if you're using IPython) interfaces.  Python 2.4 users may obtain `ctypes` from the [http://sourceforge.net/project/showfiles.php?group_id=71702 sourceforge download page].

In order to be able to invoke `python` from the command-line, setup your Windows `Path` environment variable to include the Python installation directory:
 1. Right-click on "My Computer" icon (either on the Desktop or through the Start Menu).
 2. Select the "Advanced" tab.
 3. Click the "Environment Variables" 
 4. Under "System Variables" select `Path` and click the "Edit" button.
 5. Append "`;C:\Python25`" to the value therein.

=== PostgreSQL ===

Download and run the PostgreSQL installer for either [http://www.postgresql.org/ftp/binary/v8.2.7/win32/ version 8.2.7] or [http://www.postgresql.org/ftp/binary/v8.3.1/win32/ version 8.3.1].  If using 8.2, do '''not'''  install the PostGIS version bundled with the installer. 

If you want to invoke PostgreSQL commands from the shell, append "`;C:\Program Files\PostgreSQL\8.2\bin`" to the Windows `Path`.

=== PostGIS  ===

PostGIS maintains a [http://postgis.refractions.net/download/windows/ distribution for Windows], and includes pre-built libraries for PROJ 4.5.0 and GEOS 3.0.0rc4 (both are the latest versions).   Follow the instructions for your version of PostgreSQL.

If you added the directory to PostgreSQL to your `Path` (see above), the following command may be used to easily create spatial databases:
{{{
C:\> createdb -T template_postgis <database name>
}}}

=== psycopg2 ===

Windows binary packages of the `psycopg2` module are packaged by Jason Erickson, and may be downloaded from his [http://www.stickpeople.com/projects/python/win-psycopg/ win-psycopg website].  The latest version maintained for Python 2.5 and PostgreSQL 8.3.1  is [http://www.stickpeople.com/projects/python/win-psycopg/psycopg2-2.0.7.win32-py2.5-pg8.3.1-release.exe 2.0.7].

=== GEOS ===

After PostGIS has installed, copy the GEOS (`libgeos-3-0-0rc4.dll`, `libgeos_c-1.dll`) libraries from `C:\Program Files\PostgreSQL\8.2\bin` (or wherever you installed PostgreSQL) to a location accessible to the Python interpreter (e.g., `C:\Python25`).

'''Note:''' The path to the GEOS library may be manually specified by setting `GEOS_LIBRARY_PATH` in your settings with the full path of the DLL.

=== PROJ.4 ===

Download the [ftp://ftp.remotesensing.org/proj/proj446_win32_bin.zip PROJ 4.6.0] Windows binary distribution and extract to a location on your hard drive (for example `C:\PROJ`).  Copy the PROJ DLL, `proj.dll`, from your extraction location to `C:\Python25`.  Finally, create a Windows environment variable (see above for instructions) entitled `PROJ_LIB` and have it set to the `nad` subdirectory where you extracted the PROJ distribution (e.g., `C:\PROJ\nad`).

=== GDAL ===

Download the [http://download.osgeo.org/gdal/win32/1.5/gdalwin32exe150.zip GDAL 1.5] Windows binary distribution and extract to a location on your hard drive (for example `C:\gdalwin32-1.5`).  Copy ''all'' the DLLs from the `bin` subdirectory of the extraction location to `C:\Python25`.  Finally, create another Windows environment variable called `GDAL_DATA`, setting it to the `data` subdirectory where the GDAL distribution was extracted (e.g., `C:\gdalwin32-1.5\data`).

'''Note:''' The path to the GDAL library may be manually specified by setting `GDAL_LIBRARY_PATH` in your settings with the full path of the DLL.

== Oracle ==

!GeoDjango has preliminary support for Oracle Locator/Spatial as of r6524 (though none of the advanced features of Oracle Spatial are utilized).  Oracle's express edition (XE) is ''not supported''.  Apparently, even though XE supports Locator's `SDO_GEOMETRY` objects and queries, XE does not include support for Java extensions -- which are required to construct and/or extract geometries from WKT.  For the sake of simplicity, WKT geometry construction and extraction was used when implementing the [browser:django/branches/gis/django/contrib/gis/db/backend/oracle Oracle spatial backend].  Patches for creating WKT from `SDO_GEOMETRY` statements would be required to extend support for the XE platforms.
 * ''See'' Siva Rivada's (`sravada`) forum posts in the following Oracle forum threads: "[http://forums.oracle.com/forums/thread.jspa?messageID=1340411&#1340411 Re: Problem with TO_WKTGEOMETRY/FROM_WKTGEOMETRY]", and "[http://forums.oracle.com/forums/thread.jspa?messageID=1237000&#1237000 Oracle Database 10g R2 (10.2.0.1) Express Edition (Locator) Available!!]"

=== Requirements ===
 * Oracle 10g and above with Locator (installation is way beyond the scope of this documentation).
 * [http://sourceforge.net/project/showfiles.php?group_id=84168 cx_Oracle] 4.3.2 and above.
 * GEOS (still required for Lazy-Geometries -- see installation instructions above).

== Third-Party Library Installation Tests ==

You can run these tests in order to see if the installation was successful.
{{{
$ python
}}}
{{{
#!python
>>> from django.contrib.gis.gdal import HAS_GDAL
>>> print HAS_GDAL # Will be False if GDAL libraries are not found
True
>>> from django.contrib.gis.tests import test_gdal
>>> test_gdal.run()
}}}

{{{
#!python
>>> from django.contrib.gis.tests import test_geos
>>> test_geos.run()
}}}