Separated GIS installation docs in sections
This commit is contained in:
Claude Paroz
parent
7a908747a5
commit
3084b1cfd6
|
|
@ -15,7 +15,7 @@ of spatially enabled data.
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
|
|
||||||
tutorial
|
tutorial
|
||||||
install
|
install/index
|
||||||
model-api
|
model-api
|
||||||
db-api
|
db-api
|
||||||
geoquerysets
|
geoquerysets
|
||||||
|
|
|
||||||
File diff suppressed because it is too large
Load Diff
|
|
@ -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>`_.
|
||||||
|
|
||||||
|
|
@ -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/>`_.
|
||||||
|
|
@ -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';
|
||||||
|
|
@ -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
|
||||||
Loading…
Reference in New Issue