|
|
@@ -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/>`_.
|
Claude Paroz