Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Separated GIS installation docs in sections

  • Loading branch information...
commit 3084b1cfd6110e2ef57f1a67f8b7dbda309e2e13 1 parent 7a90874
@claudep claudep authored
View
2  docs/ref/contrib/gis/index.txt
@@ -15,7 +15,7 @@ of spatially enabled data.
:maxdepth: 2
tutorial
- install
+ install/index
model-api
db-api
geoquerysets
View
1,311 docs/ref/contrib/gis/install.txt
@@ -1,1311 +0,0 @@
-.. _ref-gis-install:
-
-======================
-GeoDjango Installation
-======================
-
-.. highlight:: console
-
-Overview
-========
-In general, GeoDjango installation requires:
-
-1. :ref:`Python and Django <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
-============
-
-.. _django:
-
-Python and Django
------------------
-
-Because GeoDjango is included with Django, please refer to Django's
-:ref:`installation instructions <installing-official-release>` 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.2+ 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+
-================== ============================== ================== =========================================
-
-See also `this comparison matrix`__ on the OSGeo Wiki for
-PostgreSQL/PostGIS/GEOS/GDAL possible combinations.
-
-__ http://trac.osgeo.org/postgis/wiki/UsersWikiPostgreSQLPostGIS
-
-.. _geospatial_libs:
-
-Geospatial libraries
---------------------
-GeoDjango uses and/or provides interfaces for the following open source
-geospatial libraries:
-
-======================== ==================================== ================================ ==========================
-Program Description Required Supported Versions
-======================== ==================================== ================================ ==========================
-:ref:`GEOS <ref-geos>` Geometry Engine Open Source Yes 3.3, 3.2, 3.1, 3.0
-`PROJ.4`_ Cartographic Projections library Yes (PostgreSQL and SQLite only) 4.8, 4.7, 4.6, 4.5, 4.4
-:ref:`GDAL <ref-gdal>` Geospatial Data Abstraction Library No (but, required for SQLite) 1.9, 1.8, 1.7, 1.6, 1.5
-:ref:`GeoIP <ref-geoip>` IP-based geolocation library No 1.4
-`PostGIS`__ Spatial extensions for PostgreSQL Yes (PostgreSQL only) 2.0, 1.5, 1.4, 1.3
-`SpatiaLite`__ Spatial extensions for SQLite Yes (SQLite only) 3.0, 2.4, 2.3
-======================== ==================================== ================================ ==========================
-
-.. admonition:: Install GDAL
-
- While :ref:`gdalbuild` is technically not required, it is *recommended*.
- Important features of GeoDjango (including the :ref:`ref-layermapping`,
- geometry reprojection, 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/gaia-sins/
-
-.. _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 necessary 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: https://developer.apple.com/technologies/tools/
-
-.. _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.3.5 from the refractions Web site and untar the source
-archive::
-
- $ wget http://download.osgeo.org/geos/geos-3.3.5.tar.bz2
- $ tar xjf geos-3.3.5.tar.bz2
-
-Next, change into the directory where GEOS was unpacked, run the configure
-script, compile, and install::
-
- $ cd geos-3.3.5
- $ ./configure
- $ make
- $ sudo make install
- $ cd ..
-
-Troubleshooting
-^^^^^^^^^^^^^^^
-
-Can't find GEOS library
-~~~~~~~~~~~~~~~~~~~~~~~
-
-When GeoDjango can't find GEOS, this error is raised:
-
-.. code-block:: text
-
- 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), 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:
-
-.. code-block:: python
-
- 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``.
-
-See also :ref:`My logs are filled with GEOS-related errors <geos-exceptions-in-logfile>`.
-
-.. _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.8.0.tar.gz
- $ wget http://download.osgeo.org/proj/proj-datumgrid-1.5.tar.gz
-
-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.8.0.tar.gz
- $ cd proj-4.8.0/nad
- $ tar xzf ../../proj-datumgrid-1.5.tar.gz
- $ cd ..
-
-Finally, configure, make and install PROJ.4::
-
- $ ./configure
- $ make
- $ sudo make install
- $ cd ..
-
-.. _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.9.1.tar.gz
- $ tar xzf gdal-1.9.1.tar.gz
- $ cd gdal-1.9.1
-
-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:
-
-.. code-block:: pycon
-
- >>> 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:
-
-.. code-block:: python
-
- 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:
-
-.. code-block:: text
-
- 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:
-
-.. code-block:: apache
-
- SetEnv GDAL_DATA /usr/local/share
-
-.. _postgis:
-
-PostGIS
--------
-
-`PostGIS`__ adds geographic object support to PostgreSQL, turning it
-into a spatial database. :ref:`geosbuild`, :ref:`proj4` and
-:ref:`gdalbuild` should be installed prior to building PostGIS. You
-might also need additional libraries, see `PostGIS requirements`_.
-
-.. note::
-
- The `psycopg2`_ module is required for use as the database adaptor
- when using GeoDjango with PostGIS.
-
-.. _psycopg2: http://initd.org/psycopg/
-.. _PostGIS requirements: http://www.postgis.org/documentation/manual-2.0/postgis_installation.html#id2711662
-
-First download the source archive, and extract::
-
- $ wget http://postgis.refractions.net/download/postgis-2.0.1.tar.gz
- $ tar xzf postgis-2.0.1.tar.gz
- $ cd postgis-2.0.1
-
-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_template91` or
- :ref:`spatialdb_template_earlier` for more information.
-
-__ http://postgis.refractions.net/
-
-.. _spatialite:
-
-SpatiaLite
-----------
-
-.. 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/gaia-sins/
-
-.. _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/gaia-sins/libspatialite-sources/libspatialite-amalgamation-2.3.1.tar.gz
- $ wget http://www.gaia-gis.it/gaia-sins/spatialite-tools-sources/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/gaia-sins/libspatialite-sources/
-
-.. _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+ of
-pysqlite2. 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:
-
-.. code-block:: ini
-
- [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
- ``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:
-.. _spatialdb_template91:
-
-Creating a spatial database with PostGIS 2.0 and PostgreSQL 9.1
----------------------------------------------------------------
-
-PostGIS 2 includes an extension for Postgres 9.1 that can be used to enable
-spatial functionality::
-
- $ createdb <db name>
- $ psql <db name>
- > CREATE EXTENSION postgis;
- > CREATE EXTENSION postgis_topology;
-
-No PostGIS topology functionalities are yet available from GeoDjango, so the
-creation of the ``postgis_topology`` extension is entirely optional.
-
-.. _spatialdb_template_earlier:
-
-Creating a spatial database template for earlier versions
----------------------------------------------------------
-
-If you have an earlier version of PostGIS or PostgreSQL, the CREATE
-EXTENSION isn't available and you need to create the spatial database
-using the following instructions.
-
-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``.
-
- To complicate matters, :ref:`ubuntudebian` distributions have their
- own separate directory naming system that changes each release.
-
- 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::
-
- $ POSTGIS_SQL_PATH=`pg_config --sharedir`/contrib/postgis-2.0
- # 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 Bash shell script
-=============== =============================================
-1.3 :download:`create_template_postgis-1.3.sh`
-1.4 :download:`create_template_postgis-1.4.sh`
-1.5 :download:`create_template_postgis-1.5.sh`
-Debian/Ubuntu :download:`create_template_postgis-debian.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_spatialite_db:
-
-Creating a spatial database for SpatiaLite
-------------------------------------------
-
-After you've installed SpatiaLite, you'll need to create a number of spatial
-metadata tables in your database in order to perform spatial queries.
-
-If you're using SpatiaLite 2.4 or newer, use the ``spatialite`` utility to
-call the ``InitSpatialMetaData()`` function, like this::
-
- $ spatialite geodjango.db "SELECT InitSpatialMetaData();"
- the SPATIAL_REF_SYS table already contains some row(s)
- InitSpatiaMetaData ()error:"table spatial_ref_sys already exists"
- 0
-
-You can safely ignore the error messages shown. When you've done this, you can
-skip the rest of this section.
-
-If you're using SpatiaLite 2.3, you'll need to download a
-database-initialization file and execute its SQL queries in your database.
-
-First, get it from the `SpatiaLite Resources`__ page::
-
- $ wget http://www.gaia-gis.it/spatialite-2.3.1/init_spatialite-2.3.sql.gz
- $ gunzip init_spatialite-2.3.sql.gz
-
-Then, use the ``spatialite`` command 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:`DATABASES` ``"name"`` key
- inside your ``settings.py``.
-
-__ http://www.gaia-gis.it/spatialite-2.3.1/resources.html
-
-Add ``django.contrib.gis`` to :setting:`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
---------------------------------------------------
-
-.. note::
-
- If you're running PostGIS 1.4 or above, you can skip this step. The entry
- is already included in the default ``spatial_ref_sys`` table.
-
-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:
-
-.. code-block:: pycon
-
- $ python manage shell
- >>> from django.contrib.gis.utils import add_srs_entry
- >>> add_srs_entry(900913)
-
-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. 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://groups.google.com/group/geodjango
-__ https://code.djangoproject.com/newticket
-
-.. _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
-
-PostgreSQL's createdb fails
----------------------------
-
-When the PostgreSQL cluster uses a non-UTF8 encoding, the
-:file:`create_template_postgis-*.sh` script will fail when executing
-``createdb``::
-
- createdb: database creation failed: ERROR: new encoding (UTF8) is incompatible
- with the encoding of the template database (SQL_ASCII)
-
-The `current workaround`__ is to re-create the cluster using UTF8 (back up any
-databases before dropping the cluster).
-
-__ http://jacobian.org/writing/pg-encoding-ubuntu/
-
-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:`homebrew`
-* :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.6`__ and `2.7`__ 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.6.6/python-2.6.6-macosx10.3.dmg
-__ http://python.org/ftp/python/2.7.3/
-
-.. 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
-
-.. _homebrew:
-
-Homebrew
-^^^^^^^^
-
-`Homebrew`__ provides "recipes" for building binaries and packages from source.
-It provides recipes for the GeoDjango prerequisites on Macintosh computers
-running OS X. Because Homebrew still builds the software from source, the
-`Apple Developer Tools`_ are required.
-
-Summary::
-
- $ brew install postgresql
- $ brew install postgis
- $ brew install gdal
- $ brew install libgeoip
-
-__ http://mxcl.github.com/homebrew/
-
-.. _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
-
-.. _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 pip install psycopg2
-
-.. note::
-
- If you don't have ``pip``, follow the the :ref:`installation instructions
- <installing-official-release>` to install it.
-
-.. _pysqlite2_kyngchaos:
-
-pysqlite2
-~~~~~~~~~
-
-Follow the :ref:`pysqlite2` source install instructions, however,
-when editing the ``setup.cfg`` use the following instead:
-
-.. code-block:: ini
-
- [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``:
-
-.. code-block:: python
-
- SPATIALITE_LIBRARY_PATH='/Library/Frameworks/SQLite3.framework/SQLite3'
-
-__ http://www.gaia-gis.it/spatialite-2.3.1/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 +geos
- $ 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 ``DYLD_FALLBACK_LIBRARY_PATH`` setting so that
- the libraries can be found by Python::
-
- export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:/opt/local/lib/postgresql83
-
-__ http://www.macports.org/
-
-.. _ubuntudebian:
-
-Ubuntu & Debian GNU/Linux
--------------------------
-
-.. note::
-
- The PostGIS SQL files are not placed in the PostgreSQL share directory in
- the Debian and Ubuntu packages. Instead, they're located in a special
- directory depending on the release. In this case, use the
- :download:`create_template_postgis-debian.sh` script
-
-.. _ubuntu:
-
-Ubuntu
-^^^^^^
-
-11.10 through 12.04
-~~~~~~~~~~~~~~~~~~~
-
-In Ubuntu 11.10, PostgreSQL was upgraded to 9.1. The installation command is:
-
-.. code-block:: bash
-
- $ sudo apt-get install binutils gdal-bin libproj-dev \
- postgresql-9.1-postgis postgresql-server-dev-9.1 python-psycopg2
-
-.. _ubuntu10:
-
-10.04 through 11.04
-~~~~~~~~~~~~~~~~~~~
-
-In Ubuntu 10.04, PostgreSQL was upgraded to 8.4 and GDAL was upgraded to 1.6.
-Ubuntu 10.04 uses PostGIS 1.4, while Ubuntu 10.10 uses PostGIS 1.5 (with
-geography support). The installation command is:
-
-.. code-block:: bash
-
- $ sudo apt-get install binutils gdal-bin libproj-dev postgresql-8.4-postgis \
- postgresql-server-dev-8.4 python-psycopg2
-
-.. _ibex:
-
-8.10
-~~~~
-
-Use the synaptic package manager to install the following packages:
-
-.. code-block:: bash
-
- $ sudo apt-get install binutils gdal-bin postgresql-8.3-postgis \
- postgresql-server-dev-8.3 python-psycopg2
-
-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``
-
-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::
-
- On this version of Ubuntu the ``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:
-
- .. code-block:: bash
-
- $ 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).
-
-.. _debian:
-
-Debian
-------
-
-.. _lenny:
-
-5.0 (Lenny)
-^^^^^^^^^^^
-
-This version is comparable to Ubuntu :ref:`ibex`, so the command
-is very similar:
-
-.. code-block:: bash
-
- $ 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:
-
-.. code-block:: bash
-
- $ 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_earlier` either:
-
-* Create a symbolic link to these files:
-
- .. code-block:: bash
-
- $ 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 :download:`create_template_postgis-debian.sh` to create the spatial database.
-
-.. _windows:
-
-Windows
--------
-
-Proceed through the following sections sequentially in order to install
-GeoDjango on Windows.
-
-.. note::
-
- These instructions assume that you are using 32-bit versions of
- all programs. While 64-bit versions of Python and PostgreSQL 9.0
- are available, 64-bit versions of spatial libraries, like
- GEOS and GDAL, are not yet provided by the :ref:`OSGeo4W` installer.
-
-Python
-^^^^^^
-
-First, download the latest `Python 2.7 installer`__ from the Python Web site.
-Next, run the installer and keep the defaults -- for example, keep
-'Install for all users' checked and the installation path set as
-``C:\Python27``.
-
-.. 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.7.*
-
-__ http://python.org/download/
-
-PostgreSQL
-^^^^^^^^^^
-
-First, download the latest `PostgreSQL 9.0 installer`__ from the
-`EnterpriseDB`__ Web site. After downloading, simply run the installer,
-follow the on-screen directions, and keep the default options unless
-you know the consequences of changing them.
-
-.. note::
-
- The PostgreSQL installer creates both a new Windows user to be the
- 'postgres service account' and a ``postgres`` database superuser
- You will be prompted once to set the password for both accounts --
- make sure to remember it!
-
-When the installer completes, it will ask to launch the Application Stack
-Builder (ASB) on exit -- keep this checked, as it is necessary to
-install :ref:`postgisasb`.
-
-.. note::
-
- If installed successfully, the PostgreSQL server will run in the
- background each time the system as started as a Windows service.
- A :menuselection:`PostgreSQL 9.0` start menu group will created
- and contains shortcuts for the ASB as well as the 'SQL Shell',
- which will launch a ``psql`` command window.
-
-__ http://www.enterprisedb.com/products-services-training/pgdownload
-__ http://www.enterprisedb.com
-
-.. _postgisasb:
-
-PostGIS
-^^^^^^^
-
-From within the Application Stack Builder (to run outside of the installer,
-:menuselection:`Start --> Programs --> PostgreSQL 9.0`), select
-:menuselection:`PostgreSQL Database Server 9.0 on port 5432` from the drop down
-menu. Next, expand the :menuselection:`Categories --> Spatial Extensions` menu
-tree and select :menuselection:`PostGIS 1.5 for PostgreSQL 9.0`.
-
-After clicking next, you will be prompted to select your mirror, PostGIS
-will be downloaded, and the PostGIS installer will begin. Select only the
-default options during install (e.g., do not uncheck the option to create a
-default PostGIS database).
-
-.. note::
-
- You will be prompted to enter your ``postgres`` database superuser
- password in the 'Database Connection Information' dialog.
-
-psycopg2
-^^^^^^^^
-
-The ``psycopg2`` Python module provides the interface between Python and the
-PostgreSQL database. Download the latest `Windows installer`__ for your version
-of Python and PostgreSQL and run using the default settings. [#]_
-
-__ http://www.stickpeople.com/projects/python/win-psycopg/
-
-.. _osgeo4w:
-
-OSGeo4W
-^^^^^^^
-
-The `OSGeo4W installer`_ makes it simple to install the PROJ.4, GDAL, and GEOS
-libraries required by GeoDjango. First, download the `OSGeo4W installer`_,
-and run it. Select :menuselection:`Express Web-GIS Install` and click next.
-In the 'Select Packages' list, ensure that GDAL is selected; MapServer and
-Apache are also enabled by default, but are not required by GeoDjango and
-may be unchecked safely. After clicking next, the packages will be
-automatically downloaded and installed, after which you may exit the
-installer.
-
-.. _OSGeo4W installer: http://trac.osgeo.org/osgeo4w/
-
-Modify Windows environment
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-In order to use GeoDjango, you will need to add your Python and OSGeo4W
-directories to your Windows system ``Path``, as well as create ``GDAL_DATA``
-and ``PROJ_LIB`` environment variables. The following set of commands,
-executable with ``cmd.exe``, will set this up:
-
-.. code-block:: bat
-
- set OSGEO4W_ROOT=C:\OSGeo4W
- set PYTHON_ROOT=C:\Python27
- set GDAL_DATA=%OSGEO4W_ROOT%\share\gdal
- set PROJ_LIB=%OSGEO4W_ROOT%\share\proj
- set PATH=%PATH%;%PYTHON_ROOT%;%OSGEO4W_ROOT%\bin
- reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v Path /t REG_EXPAND_SZ /f /d "%PATH%"
- reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v GDAL_DATA /t REG_EXPAND_SZ /f /d "%GDAL_DATA%"
- reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v PROJ_LIB /t REG_EXPAND_SZ /f /d "%PROJ_LIB%"
-
-For your convenience, these commands are available in the executable batch
-script, :download:`geodjango_setup.bat`.
-
-.. note::
-
- Administrator privileges are required to execute these commands.
- To do this, right-click on :download:`geodjango_setup.bat` and select
- :menuselection:`Run as administrator`. You need to log out and log back in again
- for the settings to take effect.
-
-.. note::
-
- If you customized the Python or OSGeo4W installation directories,
- then you will need to modify the ``OSGEO4W_ROOT`` and/or ``PYTHON_ROOT``
- variables accordingly.
-
-Install Django and set up database
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Finally, :ref:`install Django <installing-official-release>` on your system.
-You do not need to create a spatial database template, as one named
-``template_postgis`` is created for you when installing PostGIS.
-
-To administer the database, you can either use the pgAdmin III program
-(:menuselection:`Start --> PostgreSQL 9.0 --> pgAdmin III`) or the
-SQL Shell (:menuselection:`Start --> PostgreSQL 9.0 --> SQL Shell`).
-For example, to create a ``geodjango`` spatial database and user, the following
-may be executed from the SQL Shell as the ``postgres`` user::
-
- postgres# CREATE USER geodjango PASSWORD 'my_passwd';
- postgres# CREATE DATABASE geodjango OWNER geodjango TEMPLATE template_postgis ENCODING 'utf8';
-
-.. 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 or 3857)
- <http://spatialreference.org/ref/sr-org/6864/prj/>`_ 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 :func:`~ctypes.util.find_library` routine from
- :mod:`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/>`_.
View
0  docs/ref/contrib/gis/create_template_postgis-1.3.sh → ...ontrib/gis/install/create_template_postgis-1.3.sh
File renamed without changes
View
0  docs/ref/contrib/gis/create_template_postgis-1.4.sh → ...ontrib/gis/install/create_template_postgis-1.4.sh
File renamed without changes
View
0  docs/ref/contrib/gis/create_template_postgis-1.5.sh → ...ontrib/gis/install/create_template_postgis-1.5.sh
File renamed without changes
View
0  ...ref/contrib/gis/create_template_postgis-debian.sh → ...rib/gis/install/create_template_postgis-debian.sh
File renamed without changes
View
0  docs/ref/contrib/gis/geodjango_setup.bat → docs/ref/contrib/gis/install/geodjango_setup.bat
File renamed without changes
View
282 docs/ref/contrib/gis/install/geolibs.txt
@@ -0,0 +1,282 @@
+.. _geospatial_libs:
+
+===============================
+Installing Geospatial libraries
+===============================
+
+GeoDjango uses and/or provides interfaces for the following open source
+geospatial libraries:
+
+======================== ==================================== ================================ ==========================
+Program Description Required Supported Versions
+======================== ==================================== ================================ ==========================
+:ref:`GEOS <ref-geos>` Geometry Engine Open Source Yes 3.3, 3.2, 3.1, 3.0
+`PROJ.4`_ Cartographic Projections library Yes (PostgreSQL and SQLite only) 4.8, 4.7, 4.6, 4.5, 4.4
+:ref:`GDAL <ref-gdal>` Geospatial Data Abstraction Library No (but, required for SQLite) 1.9, 1.8, 1.7, 1.6, 1.5
+:ref:`GeoIP <ref-geoip>` IP-based geolocation library No 1.4
+`PostGIS`__ Spatial extensions for PostgreSQL Yes (PostgreSQL only) 2.0, 1.5, 1.4, 1.3
+`SpatiaLite`__ Spatial extensions for SQLite Yes (SQLite only) 3.0, 2.4, 2.3
+======================== ==================================== ================================ ==========================
+
+.. admonition:: Install GDAL
+
+ While :ref:`gdalbuild` is technically not required, it is *recommended*.
+ Important features of GeoDjango (including the :ref:`ref-layermapping`,
+ geometry reprojection, 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/gaia-sins/
+
+
+On Debian/Ubuntu, you are advised to install the following packages which will
+install, directly or by dependency, the required geospatial libraries:
+
+.. code-block:: bash
+
+ $ sudo apt-get install binutils libproj-dev gdal-bin
+
+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
+
+Please also consult platform-specific instructions if you are on :ref:`macosx`
+or :ref:`windows`.
+
+.. _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 necessary 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: https://developer.apple.com/technologies/tools/
+
+.. _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.3.5 from the refractions Web site and untar the source
+archive::
+
+ $ wget http://download.osgeo.org/geos/geos-3.3.5.tar.bz2
+ $ tar xjf geos-3.3.5.tar.bz2
+
+Next, change into the directory where GEOS was unpacked, run the configure
+script, compile, and install::
+
+ $ cd geos-3.3.5
+ $ ./configure
+ $ make
+ $ sudo make install
+ $ cd ..
+
+Troubleshooting
+^^^^^^^^^^^^^^^
+
+Can't find GEOS library
+~~~~~~~~~~~~~~~~~~~~~~~
+
+When GeoDjango can't find GEOS, this error is raised:
+
+.. code-block:: text
+
+ 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), 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:
+
+.. code-block:: python
+
+ 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``.
+
+See also :ref:`My logs are filled with GEOS-related errors <geos-exceptions-in-logfile>`.
+
+.. _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.8.0.tar.gz
+ $ wget http://download.osgeo.org/proj/proj-datumgrid-1.5.tar.gz
+
+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.8.0.tar.gz
+ $ cd proj-4.8.0/nad
+ $ tar xzf ../../proj-datumgrid-1.5.tar.gz
+ $ cd ..
+
+Finally, configure, make and install PROJ.4::
+
+ $ ./configure
+ $ make
+ $ sudo make install
+ $ cd ..
+
+.. _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.9.1.tar.gz
+ $ tar xzf gdal-1.9.1.tar.gz
+ $ cd gdal-1.9.1
+
+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:
+
+.. code-block:: pycon
+
+ >>> 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:
+
+.. code-block:: python
+
+ 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:
+
+.. code-block:: text
+
+ 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:
+
+.. code-block:: apache
+
+ SetEnv GDAL_DATA /usr/local/share
+
+.. 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 or 3857)
+ <http://spatialreference.org/ref/sr-org/6864/prj/>`_ 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>`_.
+
View
535 docs/ref/contrib/gis/install/index.txt
@@ -0,0 +1,535 @@
+.. _ref-gis-install:
+
+======================
+GeoDjango Installation
+======================
+
+.. highlight:: console
+
+Overview
+========
+In general, GeoDjango installation requires:
+
+1. :ref:`Python and Django <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:`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, installation from
+ source may be required. When compiling the libraries from source, please
+ follow the directions closely, especially if you're a beginner.
+
+Requirements
+============
+
+.. _django:
+
+Python and Django
+-----------------
+
+Because GeoDjango is included with Django, please refer to Django's
+:ref:`installation instructions <installing-official-release>` 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.2+ 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+
+================== ============================== ================== =========================================
+
+See also `this comparison matrix`__ on the OSGeo Wiki for
+PostgreSQL/PostGIS/GEOS/GDAL possible combinations.
+
+__ http://trac.osgeo.org/postgis/wiki/UsersWikiPostgreSQLPostGIS
+
+Installation
+============
+
+Geospatial libraries
+--------------------
+
+.. toctree::
+ :maxdepth: 1
+
+ geolibs
+
+Database installation
+---------------------
+
+.. toctree::
+ :maxdepth: 1
+
+ postgis
+ spatialite
+
+Add ``django.contrib.gis`` to :setting:`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
+--------------------------------------------------
+
+.. note::
+
+ If you're running PostGIS 1.4 or above, you can skip this step. The entry
+ is already included in the default ``spatial_ref_sys`` table.
+
+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:
+
+.. code-block:: pycon
+
+ $ python manage shell
+ >>> from django.contrib.gis.utils import add_srs_entry
+ >>> add_srs_entry(900913)
+
+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. 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://groups.google.com/group/geodjango
+__ https://code.djangoproject.com/newticket
+
+.. _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:`homebrew`
+* :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.6`__ and `2.7`__ 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.6.6/python-2.6.6-macosx10.3.dmg
+__ http://python.org/ftp/python/2.7.3/
+
+.. 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
+
+.. _homebrew:
+
+Homebrew
+^^^^^^^^
+
+`Homebrew`__ provides "recipes" for building binaries and packages from source.
+It provides recipes for the GeoDjango prerequisites on Macintosh computers
+running OS X. Because Homebrew still builds the software from source, the
+`Apple Developer Tools`_ are required.
+
+Summary::
+
+ $ brew install postgresql
+ $ brew install postgis
+ $ brew install gdal
+ $ brew install libgeoip
+
+__ http://mxcl.github.com/homebrew/
+.. _Apple Developer Tools: https://developer.apple.com/technologies/tools/
+
+.. _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` (for SpatiaLite).
+
+.. note::
+
+ SpatiaLite users should consult the :ref:`spatialite_macosx` 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
+
+.. _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 pip install psycopg2
+
+.. note::
+
+ If you don't have ``pip``, follow the the :ref:`installation instructions
+ <installing-official-release>` to install it.
+
+.. _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 +geos
+ $ 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 ``DYLD_FALLBACK_LIBRARY_PATH`` setting so that
+ the libraries can be found by Python::
+
+ export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:/opt/local/lib/postgresql83
+
+__ http://www.macports.org/
+
+.. _windows:
+
+Windows
+-------
+
+Proceed through the following sections sequentially in order to install
+GeoDjango on Windows.
+
+.. note::
+
+ These instructions assume that you are using 32-bit versions of
+ all programs. While 64-bit versions of Python and PostgreSQL 9.0
+ are available, 64-bit versions of spatial libraries, like
+ GEOS and GDAL, are not yet provided by the :ref:`OSGeo4W` installer.
+
+Python
+^^^^^^
+
+First, download the latest `Python 2.7 installer`__ from the Python Web site.
+Next, run the installer and keep the defaults -- for example, keep
+'Install for all users' checked and the installation path set as
+``C:\Python27``.
+
+.. 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.7.*
+
+__ http://python.org/download/
+
+PostgreSQL
+^^^^^^^^^^
+
+First, download the latest `PostgreSQL 9.0 installer`__ from the
+`EnterpriseDB`__ Web site. After downloading, simply run the installer,
+follow the on-screen directions, and keep the default options unless
+you know the consequences of changing them.
+
+.. note::
+
+ The PostgreSQL installer creates both a new Windows user to be the
+ 'postgres service account' and a ``postgres`` database superuser
+ You will be prompted once to set the password for both accounts --
+ make sure to remember it!
+
+When the installer completes, it will ask to launch the Application Stack
+Builder (ASB) on exit -- keep this checked, as it is necessary to
+install :ref:`postgisasb`.
+
+.. note::
+
+ If installed successfully, the PostgreSQL server will run in the
+ background each time the system as started as a Windows service.
+ A :menuselection:`PostgreSQL 9.0` start menu group will created
+ and contains shortcuts for the ASB as well as the 'SQL Shell',
+ which will launch a ``psql`` command window.
+
+__ http://www.enterprisedb.com/products-services-training/pgdownload
+__ http://www.enterprisedb.com
+
+.. _postgisasb:
+
+PostGIS
+^^^^^^^
+
+From within the Application Stack Builder (to run outside of the installer,
+:menuselection:`Start --> Programs --> PostgreSQL 9.0`), select
+:menuselection:`PostgreSQL Database Server 9.0 on port 5432` from the drop down
+menu. Next, expand the :menuselection:`Categories --> Spatial Extensions` menu
+tree and select :menuselection:`PostGIS 1.5 for PostgreSQL 9.0`.
+
+After clicking next, you will be prompted to select your mirror, PostGIS
+will be downloaded, and the PostGIS installer will begin. Select only the
+default options during install (e.g., do not uncheck the option to create a
+default PostGIS database).
+
+.. note::
+
+ You will be prompted to enter your ``postgres`` database superuser
+ password in the 'Database Connection Information' dialog.
+
+psycopg2
+^^^^^^^^
+
+The ``psycopg2`` Python module provides the interface between Python and the
+PostgreSQL database. Download the latest `Windows installer`__ for your version
+of Python and PostgreSQL and run using the default settings. [#]_
+
+__ http://www.stickpeople.com/projects/python/win-psycopg/
+
+.. _osgeo4w:
+
+OSGeo4W
+^^^^^^^
+
+The `OSGeo4W installer`_ makes it simple to install the PROJ.4, GDAL, and GEOS
+libraries required by GeoDjango. First, download the `OSGeo4W installer`_,
+and run it. Select :menuselection:`Express Web-GIS Install` and click next.
+In the 'Select Packages' list, ensure that GDAL is selected; MapServer and
+Apache are also enabled by default, but are not required by GeoDjango and
+may be unchecked safely. After clicking next, the packages will be
+automatically downloaded and installed, after which you may exit the
+installer.
+
+.. _OSGeo4W installer: http://trac.osgeo.org/osgeo4w/
+
+Modify Windows environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In order to use GeoDjango, you will need to add your Python and OSGeo4W
+directories to your Windows system ``Path``, as well as create ``GDAL_DATA``
+and ``PROJ_LIB`` environment variables. The following set of commands,
+executable with ``cmd.exe``, will set this up:
+
+.. code-block:: bat
+
+ set OSGEO4W_ROOT=C:\OSGeo4W
+ set PYTHON_ROOT=C:\Python27
+ set GDAL_DATA=%OSGEO4W_ROOT%\share\gdal
+ set PROJ_LIB=%OSGEO4W_ROOT%\share\proj
+ set PATH=%PATH%;%PYTHON_ROOT%;%OSGEO4W_ROOT%\bin
+ reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v Path /t REG_EXPAND_SZ /f /d "%PATH%"
+ reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v GDAL_DATA /t REG_EXPAND_SZ /f /d "%GDAL_DATA%"
+ reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v PROJ_LIB /t REG_EXPAND_SZ /f /d "%PROJ_LIB%"
+
+For your convenience, these commands are available in the executable batch
+script, :download:`geodjango_setup.bat`.
+
+.. note::
+
+ Administrator privileges are required to execute these commands.
+ To do this, right-click on :download:`geodjango_setup.bat` and select
+ :menuselection:`Run as administrator`. You need to log out and log back in again
+ for the settings to take effect.
+
+.. note::
+
+ If you customized the Python or OSGeo4W installation directories,
+ then you will need to modify the ``OSGEO4W_ROOT`` and/or ``PYTHON_ROOT``
+ variables accordingly.
+
+Install Django and set up database
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Finally, :ref:`install Django <installing-official-release>` on your system.
+
+.. rubric:: Footnotes
+.. [#] GeoDjango uses the :func:`~ctypes.util.find_library` routine from
+ :mod:`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/>`_.
View
175 docs/ref/contrib/gis/install/postgis.txt
@@ -0,0 +1,175 @@
+.. _postgis:
+
+==================
+Installing PostGIS
+==================
+
+`PostGIS`__ adds geographic object support to PostgreSQL, turning it
+into a spatial database. :ref:`geosbuild`, :ref:`proj4` and
+:ref:`gdalbuild` should be installed prior to building PostGIS. You
+might also need additional libraries, see `PostGIS requirements`_.
+
+.. note::
+
+ The `psycopg2`_ module is required for use as the database adaptor
+ when using GeoDjango with PostGIS.
+
+.. _psycopg2: http://initd.org/psycopg/
+.. _PostGIS requirements: http://www.postgis.org/documentation/manual-2.0/postgis_installation.html#id2711662
+
+On Debian/Ubuntu, you are advised to install the following packages:
+postgresql-x.x, postgresql-x.x-postgis, postgresql-server-dev-x.x,
+python-psycopg2 (x.x matching the PostgreSQL version you want to install).
+Please also consult platform-specific instructions if you are on :ref:`macosx`
+or :ref:`windows`.
+
+Building from source
+====================
+
+First download the source archive, and extract::
+
+ $ wget http://postgis.refractions.net/download/postgis-2.0.1.tar.gz
+ $ tar xzf postgis-2.0.1.tar.gz
+ $ cd postgis-2.0.1
+
+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_template91` or
+ :ref:`spatialdb_template_earlier` for more information.
+
+__ http://postgis.refractions.net/
+
+Post-installation
+=================
+
+.. _spatialdb_template:
+.. _spatialdb_template91:
+
+Creating a spatial database with PostGIS 2.0 and PostgreSQL 9.1
+---------------------------------------------------------------
+
+PostGIS 2 includes an extension for Postgres 9.1 that can be used to enable
+spatial functionality::
+
+ $ createdb <db name>
+ $ psql <db name>
+ > CREATE EXTENSION postgis;
+ > CREATE EXTENSION postgis_topology;
+
+No PostGIS topology functionalities are yet available from GeoDjango, so the
+creation of the ``postgis_topology`` extension is entirely optional.
+
+.. _spatialdb_template_earlier:
+
+Creating a spatial database template for earlier versions
+---------------------------------------------------------
+
+If you have an earlier version of PostGIS or PostgreSQL, the CREATE
+EXTENSION isn't available and you need to create the spatial database
+using the following instructions.
+
+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``.
+
+ To complicate matters, Debian/Ubuntu distributions have their own separate
+ directory naming system that might change with time. In this case, use the
+ :download:`create_template_postgis-debian.sh` script.
+
+ 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::
+
+ $ POSTGIS_SQL_PATH=`pg_config --sharedir`/contrib/postgis-2.0
+ # 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 Bash shell script
+=============== =============================================
+1.3 :download:`create_template_postgis-1.3.sh`
+1.4 :download:`create_template_postgis-1.4.sh`
+1.5 :download:`create_template_postgis-1.5.sh`
+Debian/Ubuntu :download:`create_template_postgis-debian.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>
+
+PostgreSQL's createdb fails
+---------------------------
+
+When the PostgreSQL cluster uses a non-UTF8 encoding, the
+:file:`create_template_postgis-*.sh` script will fail when executing
+``createdb``::
+
+ createdb: database creation failed: ERROR: new encoding (UTF8) is incompatible
+ with the encoding of the template database (SQL_ASCII)
+
+The `current workaround`__ is to re-create the cluster using UTF8 (back up any
+databases before dropping the cluster).
+
+__ http://jacobian.org/writing/pg-encoding-ubuntu/
+
+Managing the database
+---------------------
+
+To administer the database, you can either use the pgAdmin III program
+(:menuselection:`Start --> PostgreSQL 9.0 --> pgAdmin III`) or the
+SQL Shell (:menuselection:`Start --> PostgreSQL 9.0 --> SQL Shell`).
+For example, to create a ``geodjango`` spatial database and user, the following
+may be executed from the SQL Shell as the ``postgres`` user::
+
+ postgres# CREATE USER geodjango PASSWORD 'my_passwd';
+ postgres# CREATE DATABASE geodjango OWNER geodjango TEMPLATE template_postgis ENCODING 'utf8';
View
222 docs/ref/contrib/gis/install/spatialite.txt
@@ -0,0 +1,222 @@
+.. _spatialite:
+
+=====================
+Installing Spatialite
+=====================
+
+`SpatiaLite`__ adds spatial support to SQLite, turning it into a full-featured
+spatial database.
+
+Check first if you can install Spatialite from system packages or binaries. For
+example, on Debian-based distributions, try to install the ``spatialite-bin``
+package. For Mac OS X, follow the
+:ref:`specific instructions below<spatialite_macosx>`. For Windows, you may
+find binaries on `Gaia-SINS`__ home page. In any case, you should always
+be able to :ref:`install from source<spatialite_source>`.
+
+When you are done with the installation process, skip to :ref:`create_spatialite_db`.
+
+__ https://www.gaia-gis.it/fossil/libspatialite
+__ http://www.gaia-gis.it/gaia-sins/
+
+.. _spatialite_source:
+
+Installing from source
+~~~~~~~~~~~~~~~~~~~~~~
+
+:ref:`GEOS and PROJ.4<geospatial_libs>` should be installed prior to building
+SpatiaLite.
+
+SQLite
+^^^^^^
+
+Check first if SQLite is compiled with the `R*Tree module`__. Run the sqlite3
+command line interface and enter the following query::
+
+ sqlite> CREATE VIRTUAL TABLE testrtree USING rtree(id,minX,maxX,minY,maxY);
+
+If you obtain an error, you will have to recompile SQLite from source. Otherwise,
+just skip this section.
+
+To install from sources, 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 ..
+
+__ http://www.sqlite.org/rtree.html
+__ http://www.sqlite.org/download.html
+
+.. _spatialitebuild :
+
+SpatiaLite library (``libspatialite``) and tools (``spatialite``)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Get the latest SpatiaLite library source and tools bundle from the
+`download page`__::
+
+ $ wget http://www.gaia-gis.it/gaia-sins/libspatialite-sources/libspatialite-amalgamation-2.4.0-5.tar.gz
+ $ wget http://www.gaia-gis.it/gaia-sins/spatialite-tools-sources/spatialite-tools-2.4.0-5.tar.gz
+ $ tar xzf libspatialite-amalgamation-2.4.0-5.tar.gz
+ $ tar xzf spatialite-tools-2.4.0-5.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 .... _spatialite
+
+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/gaia-sins/libspatialite-sources/
+
+.. _pysqlite2:
+
+pysqlite2
+^^^^^^^^^
+
+If you are on Python 2.6, you will also have to compile pysqlite2, because
+``SpatiaLite`` must be loaded as an external extension, and the required
+``enable_load_extension`` method is only available in versions 2.5+ of
+pysqlite2. Thus, download pysqlite2 2.6, and untar::
+
+ $ wget http://pysqlite.googlecode.com/files/pysqlite-2.6.3.tar.gz
+ $ tar xzf pysqlite-2.6.3.tar.gz
+ $ cd pysqlite-2.6.3
+
+Next, use a text editor (e.g., ``emacs`` or ``vi``) to edit the ``setup.cfg`` file
+to look like the following:
+
+.. code-block:: ini
+
+ [build_ext]
+ #define=
+ include_dirs=/usr/local/include
+ library_dirs=/usr/local/lib
+ libraries=sqlite3
+ #define=SQLITE_OMIT_LOAD_EXTENSION
+
+or if you are on Mac OS X:
+
+.. code-block:: ini
+
+ [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
+
+.. note::
+
+ The important thing here is to make sure you comment out 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
+
+.. _spatialite_macosx:
+
+Mac OS X-specific instructions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Mac OS X users should follow the instructions in the :ref:`kyngchaos` section,
+as it is much easier than building from source.
+
+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``:
+
+.. code-block:: python
+
+ SPATIALITE_LIBRARY_PATH='/Library/Frameworks/SQLite3.framework/SQLite3'
+
+__ http://www.gaia-gis.it/spatialite-2.3.1/binaries.html
+
+.. _create_spatialite_db:
+
+Creating a spatial database for SpatiaLite
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After you've installed SpatiaLite, you'll need to create a number of spatial
+metadata tables in your database in order to perform spatial queries.
+
+If you're using SpatiaLite 2.4 or newer, use the ``spatialite`` utility to
+call the ``InitSpatialMetaData()`` function, like this::
+
+ $ spatialite geodjango.db "SELECT InitSpatialMetaData();"
+ the SPATIAL_REF_SYS table already contains some row(s)
+ InitSpatiaMetaData ()error:"table spatial_ref_sys already exists"
+ 0
+
+You can safely ignore the error messages shown. When you've done this, you can
+skip the rest of this section.
+
+If you're using SpatiaLite 2.3, you'll need to download a
+database-initialization file and execute its SQL queries in your database.
+
+First, get it from the `SpatiaLite Resources`__ page::
+
+ $ wget http://www.gaia-gis.it/spatialite-2.3.1/init_spatialite-2.3.sql.gz
+ $ gunzip init_spatialite-2.3.sql.gz
+
+Then, use the ``spatialite`` command 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:`DATABASES` ``"name"`` key
+ inside your ``settings.py``.
+
+__ http://www.gaia-gis.it/spatialite-2.3.1/resources.html
Please sign in to comment.
Something went wrong with that request. Please try again.