diff options
Diffstat (limited to 'parts/django/docs/ref/contrib/gis/install.txt')
| -rw-r--r-- | parts/django/docs/ref/contrib/gis/install.txt | 1190 |
1 files changed, 1190 insertions, 0 deletions
diff --git a/parts/django/docs/ref/contrib/gis/install.txt b/parts/django/docs/ref/contrib/gis/install.txt new file mode 100644 index 0000000..fa8e34c --- /dev/null +++ b/parts/django/docs/ref/contrib/gis/install.txt @@ -0,0 +1,1190 @@ +.. _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 + # Creating the template spatial database. + $ createdb -E UTF8 template_postgis + $ createlang -d template_postgis plpgsql # Adding PLPGSQL language support. + # Allows non-superusers the ability to create from this template + $ psql -d postgres -c "UPDATE pg_database SET datistemplate='true' WHERE datname='template_postgis';" + # Loading the PostGIS SQL routines + $ psql -d template_postgis -f $POSTGIS_SQL_PATH/postgis.sql + $ psql -d template_postgis -f $POSTGIS_SQL_PATH/spatial_ref_sys.sql + # Enabling users to alter spatial tables. + $ psql -d template_postgis -c "GRANT ALL ON geometry_columns TO PUBLIC;" + $ psql -d template_postgis -c "GRANT ALL ON geography_columns TO PUBLIC;" + $ psql -d template_postgis -c "GRANT ALL ON spatial_ref_sys TO PUBLIC;" + +These commands may be placed in a shell script for later use; for convenience +the following scripts are available: + +=============== ========================================== +PostGIS Version Shell Script +=============== ========================================== +1.3 `create_template_postgis-1.3.sh`_ +1.4 `create_template_postgis-1.4.sh`_ +1.5 `create_template_postgis-1.5.sh`_ +=============== ========================================== + +Afterwards, you may create a spatial database by simply specifying +``template_postgis`` as the template to use (via the ``-T`` option):: + + $ createdb -T template_postgis <db name> + +.. note:: + + While the ``createdb`` command does not require database super-user privileges, + it must be executed by a database user that has permissions to create databases. + You can create such a user with the following command:: + + $ createuser --createdb <user> + +.. _create_template_postgis-1.3.sh: http://geodjango.org/docs/create_template_postgis-1.3.sh +.. _create_template_postgis-1.4.sh: http://geodjango.org/docs/create_template_postgis-1.4.sh +.. _create_template_postgis-1.5.sh: http://geodjango.org/docs/create_template_postgis-1.5.sh +.. _create_template_postgis-debian.sh: http://geodjango.org/docs/create_template_postgis-debian.sh + +.. _create_spatialite_db: + +Creating a Spatial Database for SpatiaLite +------------------------------------------- + +After the SpatiaLite library and tools have been installed, it is now possible +to create spatial database for use with GeoDjango. In order to do this, download +the spatial database initialization SQL from the `SpatiaLite Resources`__ page:: + + $ wget http://www.gaia-gis.it/spatialite/init_spatialite-2.3.sql.gz + $ gunzip init_spatialite-2.3.sql.gz + +Now, the ``spatialite`` command can be used to initialize a spatial database:: + + $ spatialite geodjango.db < init_spatialite-2.3.sql + +.. note:: + + The parameter ``geodjango.db`` is the *filename* of the SQLite database + you want to use. Use the same in the :setting:`DATABASE_NAME` + inside your ``settings.py``. + + +__ http://www.gaia-gis.it/spatialite/resources.html + + +Add ``django.contrib.gis`` to ``INSTALLED_APPS`` +------------------------------------------------ + +Like other Django contrib applications, you will *only* need to add +:mod:`django.contrib.gis` to :setting:`INSTALLED_APPS` in your settings. +This is the so that ``gis`` templates can be located -- if not done, then +features such as the geographic admin or KML sitemaps will not function properly. + +.. _addgoogleprojection: + +Add Google Projection to ``spatial_ref_sys`` table +-------------------------------------------------- + +.. versionchanged:: 1.2 + +.. note:: + + If running PostGIS 1.4 and above, the entry is already included in the + default ``spatial_ref_sys`` table. You can skip this step. + +In order to conduct database transformations to the so-called "Google" +projection (a spherical mercator projection used by Google Maps), +an entry must be added to your spatial database's ``spatial_ref_sys`` table. +Invoke the Django shell from your project and execute the +``add_srs_entry`` function:: + + $ python manage shell + >>> from django.contrib.gis.utils import add_srs_entry + >>> add_srs_entry(900913) + +.. note:: + + In Django 1.1 the name of this function is ``add_postgis_srs``. + +This adds an entry for the 900913 SRID to the ``spatial_ref_sys`` (or equivalent) +table, making it possible for the spatial database to transform coordinates in +this projection. You only need to execute this command *once* per spatial database. + +Troubleshooting +=============== + +If you can't find the solution to your problem here then participate in the +community! You can: + +* Join the ``#geodjango`` IRC channel on FreeNode (may be accessed on the + Web via `Mibbit`__). Please be patient and polite -- while you may not + get an immediate response, someone will attempt to answer your question + as soon as they see it. +* Ask your question on the `GeoDjango`__ mailing list. +* File a ticket on the `Django trac`__ if you think there's a bug. Make + sure to provide a complete description of the problem, versions used, + and specify the component as "GIS". + +__ http://www.mibbit.com/?server=irc.freenode.net&channel=%23geodjango +__ http://groups.google.com/group/geodjango +__ http://code.djangoproject.com/simpleticket + +.. _libsettings: + +Library Environment Settings +---------------------------- + +By far, the most common problem when installing GeoDjango is that the +external shared libraries (e.g., for GEOS and GDAL) cannot be located. [#]_ +Typically, the cause of this problem is that the operating system isn't aware +of the directory where the libraries built from source were installed. + +In general, the library path may be set on a per-user basis by setting +an environment variable, or by configuring the library path for the entire +system. + +``LD_LIBRARY_PATH`` environment variable +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A user may set this environment variable to customize the library paths +they want to use. The typical library directory for software +built from source is ``/usr/local/lib``. Thus, ``/usr/local/lib`` needs +to be included in the ``LD_LIBRARY_PATH`` variable. For example, the user +could place the following in their bash profile:: + + export LD_LIBRARY_PATH=/usr/local/lib + +Setting System Library Path +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +On GNU/Linux systems, there is typically a file in ``/etc/ld.so.conf``, which may include +additional paths from files in another directory, such as ``/etc/ld.so.conf.d``. +As the root user, add the custom library path (like ``/usr/local/lib``) on a +new line in ``ld.so.conf``. This is *one* example of how to do so:: + + $ sudo echo /usr/local/lib >> /etc/ld.so.conf + $ sudo ldconfig + +For OpenSolaris users, the system library path may be modified using the +``crle`` utility. Run ``crle`` with no options to see the current configuration +and use ``crle -l`` to set with the new library path. Be *very* careful when +modifying the system library path:: + + # crle -l $OLD_PATH:/usr/local/lib + +.. _binutils: + +Install ``binutils`` +^^^^^^^^^^^^^^^^^^^^ + +GeoDjango uses the ``find_library`` function (from the ``ctypes.util`` Python +module) to discover libraries. The ``find_library`` routine uses a program +called ``objdump`` (part of the ``binutils`` package) to verify a shared +library on GNU/Linux systems. Thus, if ``binutils`` is not installed on your +Linux system then Python's ctypes may not be able to find your library even if +your library path is set correctly and geospatial libraries were built perfectly. + +The ``binutils`` package may be installed on Debian and Ubuntu systems using the +following command:: + + $ sudo apt-get install binutils + +Similarly, on Red Hat and CentOS systems:: + + $ sudo yum install binutils + +Platform Specific Instructions +============================== + +.. _macosx: + +Mac OS X +-------- + +Because of the variety of packaging systems available for OS X, users have +several different options for installing GeoDjango. These options are: + +* :ref:`kyngchaos` +* :ref:`fink` +* :ref:`macports` +* :ref:`build_from_source` + +.. note:: + + Currently, the easiest and recommended approach for installing GeoDjango + on OS X is to use the KyngChaos packages. + +This section also includes instructions for installing an upgraded version +of :ref:`macosx_python` from packages provided by the Python Software +Foundation, however, this is not required. + +.. _macosx_python: + +Python +^^^^^^ + +Although OS X comes with Python installed, users can use framework +installers (`2.5`__ and `2.6`__ are available) provided by +the Python Software Foundation. An advantage to using the installer is +that OS X's Python will remain "pristine" for internal operating system +use. + +__ http://python.org/ftp/python/2.5.4/python-2.5.4-macosx.dmg +__ http://python.org/ftp/python/2.6.2/python-2.6.2-macosx2009-04-16.dmg + +.. note:: + + You will need to modify the ``PATH`` environment variable in your + ``.profile`` file so that the new version of Python is used when + ``python`` is entered at the command-line:: + + export PATH=/Library/Frameworks/Python.framework/Versions/Current/bin:$PATH + +.. _kyngchaos: + +KyngChaos Packages +^^^^^^^^^^^^^^^^^^ + +William Kyngesburye provides a number of `geospatial library binary packages`__ +that make it simple to get GeoDjango installed on OS X without compiling +them from source. However, the `Apple Developer Tools`_ are still necessary +for compiling the Python database adapters :ref:`psycopg2_kyngchaos` (for PostGIS) +and :ref:`pysqlite2_kyngchaos` (for SpatiaLite). + +.. note:: + + SpatiaLite users should consult the :ref:`spatialite_kyngchaos` section + after installing the packages for additional instructions. + +Download the framework packages for: + +* UnixImageIO +* PROJ +* GEOS +* SQLite3 (includes the SpatiaLite library) +* GDAL + +Install the packages in the order they are listed above, as the GDAL and SQLite +packages require the packages listed before them. Afterwards, you can also +install the KyngChaos binary packages for `PostgreSQL and PostGIS`__. + +After installing the binary packages, you'll want to add the following to +your ``.profile`` to be able to run the package programs from the command-line:: + + export PATH=/Library/Frameworks/UnixImageIO.framework/Programs:$PATH + export PATH=/Library/Frameworks/PROJ.framework/Programs:$PATH + export PATH=/Library/Frameworks/GEOS.framework/Programs:$PATH + export PATH=/Library/Frameworks/SQLite3.framework/Programs:$PATH + export PATH=/Library/Frameworks/GDAL.framework/Programs:$PATH + export PATH=/usr/local/pgsql/bin:$PATH + +__ http://www.kyngchaos.com/software/frameworks +__ http://www.kyngchaos.com/software/postgres + +.. note:: + + Use of these binaries requires Django 1.0.3 and above. If you are + using a previous version of Django (like 1.0.2), then you will have + to add the the following in your settings:: + + GEOS_LIBRARY_PATH='/Library/Frameworks/GEOS.framework/GEOS' + GDAL_LIBRARY_PATH='/Library/Frameworks/GDAL.framework/GDAL' + +.. _psycopg2_kyngchaos: + +psycopg2 +~~~~~~~~ + +After you've installed the KyngChaos binaries and modified your ``PATH``, as +described above, ``psycopg2`` may be installed using the following command:: + + $ sudo python easy_install psycopg2 + +.. note:: + + To use ``easy_install`` you'll need to install Python's `setuptools`_. + +.. _setuptools: http://pypi.python.org/pypi/setuptools + +.. _pysqlite2_kyngchaos: + +pysqlite2 +~~~~~~~~~ + +Follow the :ref:`pysqlite2` source install instructions, however, +when editing the ``setup.cfg`` use the following instead:: + + [build_ext] + #define= + include_dirs=/Library/Frameworks/SQLite3.framework/unix/include + library_dirs=/Library/Frameworks/SQLite3.framework/unix/lib + libraries=sqlite3 + #define=SQLITE_OMIT_LOAD_EXTENSION + +.. _spatialite_kyngchaos: + +SpatiaLite +~~~~~~~~~~ + +When :ref:`create_spatialite_db`, the ``spatialite`` program is required. +However, instead of attempting to compile the SpatiaLite tools from source, +download the `SpatiaLite Binaries`__ for OS X, and install ``spatialite`` in a +location available in your ``PATH``. For example:: + + $ curl -O http://www.gaia-gis.it/spatialite/spatialite-tools-osx-x86-2.3.1.tar.gz + $ tar xzf spatialite-tools-osx-x86-2.3.1.tar.gz + $ cd spatialite-tools-osx-x86-2.3.1/bin + $ sudo cp spatialite /Library/Frameworks/SQLite3.framework/Programs + +Finally, for GeoDjango to be able to find the KyngChaos SpatiaLite library, +add the following to your ``settings.py``:: + + SPATIALITE_LIBRARY_PATH='/Library/Frameworks/SQLite3.framework/SQLite3' + +__ http://www.gaia-gis.it/spatialite/binaries.html + +.. _fink: + +Fink +^^^^ + +`Kurt Schwehr`__ has been gracious enough to create GeoDjango packages for users +of the `Fink`__ package system. The following packages are available, depending +on which version of Python you want to use: + +* ``django-gis-py26`` +* ``django-gis-py25`` +* ``django-gis-py24`` + +__ http://schwehr.org/blog/ +__ http://www.finkproject.org/ + +.. _macports: + +MacPorts +^^^^^^^^ + +`MacPorts`__ may be used to install GeoDjango prerequisites on Macintosh +computers running OS X. Because MacPorts still builds the software from source, +the `Apple Developer Tools`_ are required. + +Summary:: + + $ sudo port install postgresql83-server + $ sudo port install geos + $ sudo port install proj + $ sudo port install postgis + $ sudo port install gdal + $ sudo port install libgeoip + +.. note:: + + You will also have to modify the ``PATH`` in your ``.profile`` so + that the MacPorts programs are accessible from the command-line:: + + export PATH=/opt/local/bin:/opt/local/lib/postgresql83/bin + + In addition, add the ``FALLBACK_DYLD_LIBRARY_PATH`` setting so that + the libraries can be found by Python:: + + export FALLBACK_DYLD_LIBRARY_PATH=/opt/local/lib:/opt/local/lib/postgresql83 + +__ http://www.macports.org/ + +.. _ubuntudebian: + +Ubuntu & Debian GNU/Linux +------------------------- + +.. _ubuntu: + +Ubuntu +^^^^^^ + +.. _heron: + +8.04 and lower +~~~~~~~~~~~~~~ + +The 8.04 (and lower) versions of Ubuntu use GEOS v2.2.3 in their binary packages, +which is incompatible with GeoDjango. Thus, do *not* use the binary packages +for GEOS or PostGIS and build some prerequisites from source, per the instructions +in this document; however, it is okay to use the PostgreSQL binary packages. + +For more details, please see the Debian instructions for :ref:`etch` below. + +.. _ibex: + +8.10 +~~~~ + +Use the synaptic package manager to install the following packages:: + + $ sudo apt-get install binutils libgdal1-1.5.0 postgresql-8.3-postgis postgresql-server-dev-8.3 python-psycopg2 python-setuptools + +Afterwards, you may install Django with Python's ``easy_install`` script (the +Ubuntu package ``python-django`` uses an older version missing several +important bug fixes for GeoDjango):: + + $ sudo easy_install Django + +That's it! For the curious, the required binary prerequisites packages are: + +* ``binutils``: for ctypes to find libraries +* ``postgresql-8.3`` +* ``postgresql-server-dev-8.3``: for ``pg_config`` +* ``postgresql-8.3-postgis``: for PostGIS 1.3.3 +* ``libgeos-3.0.0``, and ``libgeos-c1``: for GEOS 3.0.0 +* ``libgdal1-1.5.0``: for GDAL 1.5.0 library +* ``proj``: for PROJ 4.6.0 -- but no datum shifting files, see note below +* ``python-psycopg2`` +* ``python-setuptools``: for ``easy_install`` + +Optional packages to consider: + +* ``libgeoip1``: for :ref:`GeoIP <ref-geoip>` support +* ``gdal-bin``: for GDAL command line programs like ``ogr2ogr`` +* ``python-gdal`` for GDAL's own Python bindings -- includes interfaces for raster manipulation + +.. note:: + + The Ubuntu ``proj`` package does not come with the datum shifting files + installed, which will cause problems with the geographic admin because + the ``null`` datum grid is not available for transforming geometries to the + spherical mercator projection. A solution is to download the + datum-shifting files, create the grid file, and install it yourself:: + + $ wget http://download.osgeo.org/proj/proj-datumgrid-1.4.tar.gz + $ mkdir nad + $ cd nad + $ tar xzf ../proj-datumgrid-1.4.tar.gz + $ nad2bin null < null.lla + $ sudo cp null /usr/share/proj + + Otherwise, the Ubuntu ``proj`` package is fine for general use as long as you + do not plan on doing any database transformation of geometries to the + Google projection (900913). + +.. note:: + + The PostGIS SQL files are not placed the PostgreSQL share directory in the + Ubuntu packages. Use the `create_template_postgis-debian.sh`_ script + instead when :ref:`spatialdb_template`. + +.. _debian: + +Debian +------ + +.. _etch: + +4.0 (Etch) +^^^^^^^^^^ +The situation here is the same as that of Ubuntu :ref:`heron` -- in other words, +some packages must be built from source to work properly with GeoDjango. + +Binary Packages +~~~~~~~~~~~~~~~ +The following command will install acceptable binary packages, as well as +the development tools necessary to build the rest of the requirements:: + + $ sudo apt-get install binutils bzip2 gcc g++ flex make postgresql-8.1 postgresql-server-dev-8.1 python-ctypes python-psycopg2 python-setuptools + +Required package information: + +* ``binutils``: for ctypes to find libraries +* ``bzip2``: for decompressing the source packages +* ``gcc``, ``g++``, ``make``: GNU developer tools used to compile the libraries +* ``flex``: required to build PostGIS +* ``postgresql-8.1`` +* ``postgresql-server-dev-8.1``: for ``pg_config`` +* ``python-ctypes``: Python 2.4 needs to have ctypes installed separately +* ``python-psycopg2`` +* ``python-setuptools``: for ``easy_install`` + +Optional packages: + +* ``libgeoip``: for :ref:`GeoIP <ref-geoip>` support + +Source Packages +~~~~~~~~~~~~~~~ +You will still have to install :ref:`geosbuild`, :ref:`proj4`, +:ref:`postgis`, and :ref:`gdalbuild` from source. Please follow the +directions carefully. + +.. _lenny: + +5.0 (Lenny) +^^^^^^^^^^^ +This version is comparable to Ubuntu :ref:`ibex`, so the command +is very similar:: + + $ sudo apt-get install binutils libgdal1-1.5.0 postgresql-8.3 postgresql-8.3-postgis postgresql-server-dev-8.3 python-psycopg2 python-setuptools + +This assumes that you are using PostgreSQL version 8.3. Else, replace ``8.3`` +in the above command with the appropriate PostgreSQL version. + +.. note:: + + Please read the note in the Ubuntu :ref:`ibex` install documentation + about the ``proj`` package -- it also applies here because the package does + not include the datum shifting files. + +.. _post_install: + +Post-installation Notes +~~~~~~~~~~~~~~~~~~~~~~~ + +If the PostgreSQL database cluster was not initiated after installing, then it +can be created (and started) with the following command:: + + $ sudo pg_createcluster --start 8.3 main + +Afterwards, the ``/etc/init.d/postgresql-8.3`` script should be used to manage +the starting and stopping of PostgreSQL. + +In addition, the SQL files for PostGIS are placed in a different location on +Debian 5.0 . Thus when :ref:`spatialdb_template` either: + +* Create a symbolic link to these files:: + + $ sudo ln -s /usr/share/postgresql-8.3-postgis/{lwpostgis,spatial_ref_sys}.sql /usr/share/postgresql/8.3 + + If not running PostgreSQL 8.3, then replace ``8.3`` in the command above with the correct version. + +* Or use the `create_template_postgis-debian.sh`_ to create the spatial database. + +.. _windows: + +Windows XP +---------- + +Python +^^^^^^ + +First, download the `Python 2.6 installer`__ from the Python Web site. Next, +execute the installer and use defaults, e.g., keep 'Install for all users' +checked and the installation path set as ``C:\Python26``. + +.. note:: + + You may already have a version of Python installed in ``C:\python`` as ESRI + products sometimes install a copy there. *You should still install a + fresh version of Python 2.6.* + +__ http://python.org/ftp/python/2.6.2/python-2.6.2.msi + +PostgreSQL +^^^^^^^^^^ + +First, select a mirror and download the latest `PostgreSQL 8.3 installer`__ from +the EnterpriseDB Web site. + +.. note:: + + PostgreSQL 8.3 is required because PostGIS is not available yet for 8.4. + +After downloading, simply click on the installer, follow the +on-screen directions, and keep the default options (e.g., keep the installation +path as ``C:\Program Files\PostgreSQL\8.3``). + +.. note:: + + This PostgreSQL installation process will create both a new windows user to be the + 'postgres service account' and a special 'postgres superuser' to own the database + cluster. You will be prompted to set a password for both users (make sure to write + them down!). To see basic details on the 'service user' account right click on + 'My Computer' and select 'Manage' or go to: Control Panel -> Administrative Tools -> + Computer Management -> System Tools -> Local Users and Groups. + +If installed successfully, the PostgreSQL server will run in the background each time +the system as started as a Windows service. When finished, the installer should launch +the Application Stack Builder (ASB) -- use this to install PostGIS, see instructions +below for more details. A 'PostgreSQL 8.3' start menu group should be created that +contains shortcuts for the ASB and 'Command Prompt', which launches a terminal window +in the PostgreSQL directory. + +__ http://www.enterprisedb.com/products/pgdownload.do#windows + +PostGIS +^^^^^^^ + +From the Application Stack Builder (Programs -> PostgreSQL 8.3), select +'PostgreSQL Database Server 8.3 on port 5432' from the drop down menu. Next, +select 'PostGIS 1.3.6 for PostgreSQL 8.3' from the 'Spatial Extensions' tree +in the list. Select only the default options during install (do not uncheck +the option to create a default PostGIS database). + +.. note:: + + You will be prompted to enter your 'postgres superuser' password in the + 'Database Connection Information' dialog. + +psycopg2 +^^^^^^^^ + +The ``psycopg2`` Python module provides the interface between Python and the +PostgreSQL database. Download the `Windows installer`__ (v2.0.10) and run +using the default settings. [#]_ + +__ http://www.stickpeople.com/projects/python/win-psycopg/psycopg2-2.0.10.win32-py2.6-pg8.3.7-release.exe + +GeoDjango Installer +^^^^^^^^^^^^^^^^^^^ + +Download the `GeoDjango Installer`__; this was created [#]_ to simplify the rest +of the process for installing GeoDjango on Windows platforms. The installer +automatically installs Django 1.1, GDAL 1.6.0, PROJ 4.6.1 (including datum grid +files), and configures the necessary environment variables. + +Once the installer has completed, log out and log back in so that the +modifications to the system environment variables take effect, and you +should be good to go. + +.. note:: + + The installer modifies the system ``Path`` environment variable to + include ``C:\Program Files\PostgreSQL\8.3\bin`` and + ``C:\Program Files\GeoDjango\bin``. This is required so that Python + may find the GEOS DLL provided by PostGIS and the GDAL DLL provided + by the installer. The installer also sets the ``GDAL_DATA`` and + ``PROJ_LIB`` environment variables. + +__ http://geodjango.org/windows/GeoDjango_Installer.exe + +.. rubric:: Footnotes +.. [#] The datum shifting files are needed for converting data to and from certain projections. + For example, the PROJ.4 string for the `Google projection (900913) <http://spatialreference.org/ref/epsg/900913/proj4>`_ + requires the ``null`` grid file only included in the extra datum shifting files. + It is easier to install the shifting files now, then to have debug a problem caused by their absence later. +.. [#] Specifically, GeoDjango provides support for the `OGR <http://gdal.org/ogr>`_ library, a component of GDAL. +.. [#] See `GDAL ticket #2382 <http://trac.osgeo.org/gdal/ticket/2382>`_. +.. [#] GeoDjango uses the `find_library <http://docs.python.org/library/ctypes.html#finding-shared-libraries>`_ + routine from ``ctypes.util`` to locate shared libraries. +.. [#] The ``psycopg2`` Windows installers are packaged and maintained by + `Jason Erickson <http://www.stickpeople.com/projects/python/win-psycopg/>`_. +.. [#] The source code for the installer is available in the `nsis_installer <http://geodjango.org/hg/nsis_installer/>`_ + GeoDjango mercurial repository. |