[[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) * 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 to use don't forget to use: {{{ $ 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 etch you can use python-ctypes and don't forget to install swig. * Configure, make, and install. {{{ $ apt-get install swig $ ./configure $ make # make install }}} * You must have g++ already installed. === 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]). * On Debian etch install the flex package. (May bee its required in other Linux) {{{ apt-get install flex }}} * 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 $ 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 ; }}} * Now that you have installed postgis, if you get errors about not finding some libraries, make sure to edit /etc/ld.so.conf in order to add /usr/local/lib , and then run {{{ $ ldconfig }}} * 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. == Installation Test == 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 }}} {{{ #!python >>> from django.contrib.gis.tests import test_geos >>> test_geos.run() }}}