[[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) * Debian etch (2.6 Kernel) * Ubuntu 7.0 (2.6 Kernel) * Centos 5 (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`). 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 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.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 }}} * To detect the correct `site-packages` directory, the following command may be used: {{{ $ python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()" }}} === 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], but in Debian etch you may install the `python-ctypes` package. * If you are running Mac OS X 10.5 and using 3.0.0RC4 you will need to apply two quick hand-patches from [http://trac.osgeo.org/geos/ticket/162 here] and [http://lists.osgeo.org/pipermail/geos-devel/2007-November/003125.html here]. * Configure, make, and install (`g++` is required for compilation) {{{ $ ./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 }}} * 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 $ createdb -O $ createlang plpgsql $ psql -d -f /usr/postgres/8.2/share/lwpostgis.sql $ psql -d -f /usr/postgres/8.2/share/spatial_ref_sys.sql $ psql =# GRANT SELECT, UPDATE, INSERT, DELETE ON geometry_columns TO ; =# GRANT SELECT ON spatial_ref_sys TO ; }}} * 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. 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.5. 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). 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. 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 }}} === 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]. === GEOS === 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\bin` (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. A snapshot (0.9.0 Preview-2) windows installer of [http://www.qgis.org/ Quantum GIS] (QGIS) can be obtained from [http://download.qgis.org/qgis/win32/qgis_setup0.9.0.01_09_2007.exe here]. Once installed, copy all the DLLs from `C:\Program Files\Quantum GIS` to `C:\Python25`: Do not overwrite any dlls that come from PostGIS. == 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� Re: Problem with TO_WKTGEOMETRY/FROM_WKTGEOMETRY]", and "[http://forums.oracle.com/forums/thread.jspa?messageID=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() }}}