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

Installation of !GeoDjango also requires the installation of existing open source geographic libraries and a spatial database -- currently only PostGIS.  This section will describe the installation process for these prerequisites.  !GeoDjango is best supported on Linux/UNIX platforms, but also works 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)
   * Ubuntu 7.0 (2.6 Kernel)
 * 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}}}).  The {{{ctypes}}} module needs to be installed as well.
   * ''Recommended:'' Python 2.5 is recommended because the {{{ctypes}}} module comes included.  [http://www.python.org/download/releases/2.5.1/ Python 2.5.1] 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 and v8.2 of PostgreSQL.
   * On Ubuntu Feisty, you'll need the apt packages {{{postgresql-server-dev-8.x}}} (the development headers are needed for PostGIS compilation) and {{{postgresql-8.x}}}.
 * '''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.6.tar.gz 2.0.6].

=== Django ===
 * !GeoDjango exists in the {{{gis}}} branch from SVN:
{{{
$ svn co http://code.djangoproject.com/svn/django/branches/gis django_gis
$ ln -s django_gis/django /path/to/site-packages/django
}}}

=== GEOS ===
 * We have been developing using [http://geos.refractions.net/ GEOS] 3.0.0RC4, and have not tested using GEOS 2.x.  Despite the "RC" nomenclature, 3.0.0RC4 is quite stable, and will be renamed to 3.0.0 after FOSS4G.
   * ''See'' Mateusz Loskot (GEOS lead developer), [http://lists.refractions.net/pipermail/geos-devel/2007-August/002936.html Note about GEOS 3.0.0 release].
 * !GeoDjango has its own GEOS {{{ctypes}}} wrapper; you do ''not'' need to enable the existing GEOS Python bindings.
   * {{{ctypes}}} 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]
 * Configure, make, and install.
{{{
$ ./configure
$ make
# make install
}}}

=== PROJ.4 ===
 * Latest [http://proj.maptools.org/ PROJ.4] version is 4.5.0.  We have no reason to believe that previous versions (''e.g.'', 4.4.x, 4.3.x) will not work.
 * First, download the PROJ [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 source.  For example, if PROJ was unzipped in a directory named {{{proj}}}, then untar these files in {{{proj/nad}}}.  Do this '''before''' you do the configure/make/install dance.
   * ''See'' [http://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].
 * Next, configure, make and install.
{{{
$ ./configure
$ make
# make install 
}}}

=== PostGIS ===
 * ''Required'':  PostGIS ~~v1.1.0~~ v1.2.1 and above.  1.1.0 support is currently pending, ''see'' #5498.
 * ''Recommended'': Postgis v1.3.1 [http://postgis.refractions.net/download/ PostGIS] (this is the [http://postgis.refractions.net/news/20070809/ latest version]).
 * First build & install PostGIS.
{{{
$ ./configure --with-geos --with-proj
$ make
# make install
}}}

 * 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 `pg_config --sharedir` 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>=# GRANT SELECT, UPDATE, INSERT, DELETE ON geometry_columns TO <user>;
<db_name>=# GRANT SELECT ON spatial_ref_sys TO <user>;
}}}
 
 * Finally, update your {{{settings.py}}} to reflect the name and user for the spatially enabled database.  So far, we only plan to support the psycopg2 backend, thus: {{{DATABASE_ENGINE='postgresql_psycopg2'}}}.

=== GDAL ===
 * ''Highly Recommended'': Some features (''e.g.'', a large number of {{{SpatialRefSys}}} model routines) require GDAL, but it is not necessary for core functionality like spatial queries.  
 * GDAL/OGR includes useful for coordinate transformations and reading/writing ''both'' vector (''e.g.'', SHP) and raster (''e.g.'', GeoTIFF) geographic data.
   * For example, the following command will convert your SHP file into [http://en.wikipedia.org/wiki/WGS84 WGS84] (standard lat/lon).  Then you can import directly into your database using {{{shp2pgsql}}} (utility from PostGIS):
{{{
ogr2ogr -t_srs WGS84 output.shp input.shp
}}}
 * Latest [http://www.gdal.org/download.html GDAL] version is 1.4.2.  Configure with GEOS then make (use {{{gmake}}} on Solaris platforms) and install:
{{{
$ ./configure --with-geos
$ make
# make install
}}}
 * As of r5397 there's a {{{ctypes}}} layer for GDAL/OGR, no additional Python bindings are needed.  
 * If you still want to use the GDAL Python API for your own applications, then the following configuration flags:
   * {{{--with-python}}} {{{--without-ngpython}}}: the deprecated, but stable API.
   * {{{--without-python}}} {{{--with-ngpython}}}: the "next-generation" SWIG-based bindings -- used to problematic for Python 2.5 users, but the GDAL team has solved a lot of these issues in 1.4.2.
   * ''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.1/python-2.5.1.msi Python installer].  We highly recommend you use Python 2.5 or greater (2.5.1 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 from [http://www.postgresql.org/ftp/binary/v8.2.4/win32/ here].  Do '''not'''  install the PostGIS version bundled with this installer.  The latest version of PostgreSQL is 8.2.4.

=== 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.2.4  is [http://www.stickpeople.com/projects/python/win-psycopg/psycopg2-2.0.6.win32-py2.5-pg8.2.4-release.exe pyscopg2 2.0.6].

=== 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).  You may download the latest [http://postgis.refractions.net/download/windows/pg82/postgis-pg82-setup-1.3.1-1.exe PostGIS (1.3.1) here].  Run this ''after'' the PostgreSQL installer.

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

=== GDAL/OGR ===

The premiere GDAL/OGR binary package for Windows is [http://fwtools.maptools.org/ FWTools], however, the libraries I downloaded (1.4.1 at the time) were missing functions needed for the library interface -- I need to investigate again to provide additional details.  This is the reason why QGIS is used to obtain compiled GDAL libraries for Windows.

[http://www.qgis.org/ Quantum GIS] (QGIS) provides a Windows installer, [http://download.qgis.org/qgis/ download] the Windows package (latest is 0.8.1), and install.  Once installed, copy the following DLLs from {{{C:\Program Files\Quantum GIS}}} to {{{C:\Python25}}}: {{{gdal14.dll}}}, {{{libgdal-1.dll}}}, and {{{proj.dll}}} (since GDAL libraries are linked to this specific PROJ library).