mirror of
https://github.com/django/django.git
synced 2024-12-24 10:05:46 +00:00
d036b87126
git-svn-id: http://code.djangoproject.com/svn/django/trunk@16733 bcc190cf-cafb-0310-a4f2-bffc1f526a37
1252 lines
43 KiB
Plaintext
1252 lines
43 KiB
Plaintext
.. _ref-gis-install:
|
|
|
|
======================
|
|
GeoDjango Installation
|
|
======================
|
|
|
|
Overview
|
|
========
|
|
In general, GeoDjango installation requires:
|
|
|
|
1. Python and :ref:`django`
|
|
2. :ref:`spatial_database`
|
|
3. :ref:`geospatial_libs`
|
|
|
|
Details for each of the requirements and installation instructions
|
|
are provided in the sections below. In addition, platform-specific
|
|
instructions are available for:
|
|
|
|
* :ref:`macosx`
|
|
* :ref:`ubuntudebian`
|
|
* :ref:`windows`
|
|
|
|
.. admonition:: Use the Source
|
|
|
|
Because GeoDjango takes advantage of the latest in the open source geospatial
|
|
software technology, recent versions of the libraries are necessary.
|
|
If binary packages aren't available for your platform,
|
|
:ref:`installation from source <build_from_source>`
|
|
may be required. When compiling the libraries from source, please follow the
|
|
directions closely, especially if you're a beginner.
|
|
|
|
Requirements
|
|
============
|
|
|
|
.. _django:
|
|
|
|
Python and Django
|
|
-----------------
|
|
|
|
Because GeoDjango is included with Django, please refer to Django's
|
|
:doc:`installation instructions </intro/install>` for details on how to install.
|
|
|
|
.. _spatial_database:
|
|
|
|
Spatial Database
|
|
----------------
|
|
PostgreSQL (with PostGIS), MySQL, Oracle, and SQLite (with SpatiaLite) are
|
|
the spatial databases currently supported.
|
|
|
|
.. note::
|
|
|
|
PostGIS is recommended, because it is the most mature and feature-rich
|
|
open source spatial database.
|
|
|
|
The geospatial libraries required for a GeoDjango installation depends
|
|
on the spatial database used. The following lists the library requirements,
|
|
supported versions, and any notes for each of the supported database backends:
|
|
|
|
================== ============================== ================== ==========================================================
|
|
Database Library Requirements Supported Versions Notes
|
|
================== ============================== ================== ==========================================================
|
|
PostgreSQL GEOS, PROJ.4, PostGIS 8.1+ Requires PostGIS.
|
|
MySQL GEOS 5.x Not OGC-compliant; limited functionality.
|
|
Oracle GEOS 10.2, 11 XE not supported; not tested with 9.
|
|
SQLite GEOS, GDAL, PROJ.4, SpatiaLite 3.6.+ Requires SpatiaLite 2.3+, pysqlite2 2.5+, and Django 1.1.
|
|
================== ============================== ================== ==========================================================
|
|
|
|
.. _geospatial_libs:
|
|
|
|
Geospatial Libraries
|
|
--------------------
|
|
GeoDjango uses and/or provides interfaces for the following open source
|
|
geospatial libraries:
|
|
|
|
======================== ==================================== ================================ ==========================
|
|
Program Description Required Supported Versions
|
|
======================== ==================================== ================================ ==========================
|
|
:ref:`GEOS <ref-geos>` Geometry Engine Open Source Yes 3.2, 3.1, 3.0
|
|
`PROJ.4`_ Cartographic Projections library Yes (PostgreSQL and SQLite only) 4.7, 4.6, 4.5, 4.4
|
|
:ref:`GDAL <ref-gdal>` Geospatial Data Abstraction Library No (but, required for SQLite) 1.8, 1.7, 1.6, 1.5, 1.4
|
|
:ref:`GeoIP <ref-geoip>` IP-based geolocation library No 1.4
|
|
`PostGIS`__ Spatial extensions for PostgreSQL Yes (PostgreSQL only) 1.5, 1.4, 1.3
|
|
`SpatiaLite`__ Spatial extensions for SQLite Yes (SQLite only) 2.4, 2.3
|
|
======================== ==================================== ================================ ==========================
|
|
|
|
.. admonition:: Install GDAL
|
|
|
|
While :ref:`gdalbuild` is technically not required, it is *recommended*.
|
|
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/spatialite/index.html
|
|
|
|
.. _build_from_source:
|
|
|
|
Building from Source
|
|
====================
|
|
|
|
When installing from source on UNIX and GNU/Linux systems, please follow
|
|
the installation instructions carefully, and install the libraries in the
|
|
given order. If using MySQL or Oracle as the spatial database, only GEOS
|
|
is required.
|
|
|
|
.. note::
|
|
|
|
On Linux platforms, it may be 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: http://developer.apple.com/tools/xcode/
|
|
|
|
.. _geosbuild:
|
|
|
|
GEOS
|
|
----
|
|
|
|
GEOS is a C++ library for performing geometric operations, and is the default
|
|
internal geometry representation used by GeoDjango (it's behind the "lazy"
|
|
geometries). Specifically, the C API library is called (e.g., ``libgeos_c.so``)
|
|
directly from Python using ctypes.
|
|
|
|
First, download GEOS 3.2 from the refractions Web site and untar the source
|
|
archive::
|
|
|
|
$ wget http://download.osgeo.org/geos/geos-3.2.2.tar.bz2
|
|
$ tar xjf geos-3.2.2.tar.bz2
|
|
|
|
Next, change into the directory where GEOS was unpacked, run the configure
|
|
script, compile, and install::
|
|
|
|
$ cd geos-3.2.2
|
|
$ ./configure
|
|
$ make
|
|
$ sudo make install
|
|
$ cd ..
|
|
|
|
Troubleshooting
|
|
^^^^^^^^^^^^^^^
|
|
|
|
Can't find GEOS Library
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
When GeoDjango can't find GEOS, this error is raised::
|
|
|
|
ImportError: Could not find the GEOS library (tried "geos_c"). Try setting GEOS_LIBRARY_PATH in your settings.
|
|
|
|
The most common solution is to properly configure your :ref:`libsettings` *or* set
|
|
:ref:`geoslibrarypath` in your settings.
|
|
|
|
If using a binary package of GEOS (e.g., on Ubuntu), you may need to :ref:`binutils`.
|
|
|
|
.. _geoslibrarypath:
|
|
|
|
``GEOS_LIBRARY_PATH``
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
If your GEOS library is in a non-standard location, or you don't want to
|
|
modify the system's library path then the :setting:`GEOS_LIBRARY_PATH`
|
|
setting may be added to your Django settings file with the full path to the
|
|
GEOS C library. For example::
|
|
|
|
GEOS_LIBRARY_PATH = '/home/bob/local/lib/libgeos_c.so'
|
|
|
|
.. note::
|
|
|
|
The setting must be the *full* path to the **C** shared library; in
|
|
other words you want to use ``libgeos_c.so``, not ``libgeos.so``.
|
|
|
|
.. _proj4:
|
|
|
|
PROJ.4
|
|
------
|
|
|
|
`PROJ.4`_ is a library for converting geospatial data to different coordinate
|
|
reference systems.
|
|
|
|
First, download the PROJ.4 source code and datum shifting files [#]_::
|
|
|
|
$ wget http://download.osgeo.org/proj/proj-4.7.0.tar.gz
|
|
$ wget http://download.osgeo.org/proj/proj-datumgrid-1.5.zip
|
|
|
|
Next, untar the source code archive, and extract the datum shifting files in the
|
|
``nad`` subdirectory. This must be done *prior* to configuration::
|
|
|
|
$ tar xzf proj-4.7.0.tar.gz
|
|
$ cd proj-4.7.0/nad
|
|
$ unzip ../../proj-datumgrid-1.5.zip
|
|
$ cd ..
|
|
|
|
Finally, configure, make and install PROJ.4::
|
|
|
|
$ ./configure
|
|
$ make
|
|
$ sudo make install
|
|
$ cd ..
|
|
|
|
.. _postgis:
|
|
|
|
PostGIS
|
|
-------
|
|
|
|
`PostGIS`__ adds geographic object support to PostgreSQL, turning it
|
|
into a spatial database. :ref:`geosbuild` and :ref:`proj4` should be
|
|
installed prior to building PostGIS.
|
|
|
|
.. note::
|
|
|
|
The `psycopg2`_ module is required for use as the database adaptor
|
|
when using GeoDjango with PostGIS.
|
|
|
|
.. _psycopg2: http://initd.org/projects/psycopg2
|
|
|
|
First download the source archive, and extract::
|
|
|
|
$ wget http://postgis.refractions.net/download/postgis-1.5.2.tar.gz
|
|
$ tar xzf postgis-1.5.2.tar.gz
|
|
$ cd postgis-1.5.2
|
|
|
|
Next, configure, make and install PostGIS::
|
|
|
|
$ ./configure
|
|
|
|
Finally, make and install::
|
|
|
|
$ make
|
|
$ sudo make install
|
|
$ cd ..
|
|
|
|
.. note::
|
|
|
|
GeoDjango does not automatically create a spatial database. Please
|
|
consult the section on :ref:`spatialdb_template` for more information.
|
|
|
|
__ http://postgis.refractions.net/
|
|
|
|
.. _gdalbuild:
|
|
|
|
GDAL
|
|
----
|
|
|
|
`GDAL`__ is an excellent open source geospatial library that has support for
|
|
reading most vector and raster spatial data formats. Currently, GeoDjango only
|
|
supports :ref:`GDAL's vector data <ref-gdal>` capabilities [#]_.
|
|
:ref:`geosbuild` and :ref:`proj4` should be installed prior to building GDAL.
|
|
|
|
First download the latest GDAL release version and untar the archive::
|
|
|
|
$ wget http://download.osgeo.org/gdal/gdal-1.8.0.tar.gz
|
|
$ tar xzf gdal-1.8.0.tar.gz
|
|
$ cd gdal-1.8.0
|
|
|
|
Configure, make and install::
|
|
|
|
$ ./configure
|
|
$ make # Go get some coffee, this takes a while.
|
|
$ sudo make install
|
|
$ cd ..
|
|
|
|
.. note::
|
|
|
|
Because GeoDjango has it's own Python interface, the preceding instructions
|
|
do not build GDAL's own Python bindings. The bindings may be built by
|
|
adding the ``--with-python`` flag when running ``configure``. See
|
|
`GDAL/OGR In Python`__ for more information on GDAL's bindings.
|
|
|
|
If you have any problems, please see the troubleshooting section below for
|
|
suggestions and solutions.
|
|
|
|
__ http://trac.osgeo.org/gdal/
|
|
__ http://trac.osgeo.org/gdal/wiki/GdalOgrInPython
|
|
|
|
.. _gdaltrouble:
|
|
|
|
Troubleshooting
|
|
^^^^^^^^^^^^^^^
|
|
|
|
Can't find GDAL Library
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
When GeoDjango can't find the GDAL library, the ``HAS_GDAL`` flag
|
|
will be false::
|
|
|
|
>>> from django.contrib.gis import gdal
|
|
>>> gdal.HAS_GDAL
|
|
False
|
|
|
|
The solution is to properly configure your :ref:`libsettings` *or* set
|
|
:ref:`gdallibrarypath` in your settings.
|
|
|
|
.. _gdallibrarypath:
|
|
|
|
``GDAL_LIBRARY_PATH``
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
If your GDAL library is in a non-standard location, or you don't want to
|
|
modify the system's library path then the :setting:`GDAL_LIBRARY_PATH`
|
|
setting may be added to your Django settings file with the full path to
|
|
the GDAL library. For example::
|
|
|
|
GDAL_LIBRARY_PATH = '/home/sue/local/lib/libgdal.so'
|
|
|
|
.. _gdaldata:
|
|
|
|
Can't find GDAL data files (``GDAL_DATA``)
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
When installed from source, GDAL versions 1.5.1 and below have an autoconf bug
|
|
that places data in the wrong location. [#]_ This can lead to error messages
|
|
like this::
|
|
|
|
ERROR 4: Unable to open EPSG support file gcs.csv.
|
|
...
|
|
OGRException: OGR failure.
|
|
|
|
The solution is to set the ``GDAL_DATA`` environment variable to the location of the
|
|
GDAL data files before invoking Python (typically ``/usr/local/share``; use
|
|
``gdal-config --datadir`` to find out). For example::
|
|
|
|
$ export GDAL_DATA=`gdal-config --datadir`
|
|
$ python manage.py shell
|
|
|
|
If using Apache, you may need to add this environment variable to your configuration
|
|
file::
|
|
|
|
SetEnv GDAL_DATA /usr/local/share
|
|
|
|
.. _spatialite:
|
|
|
|
SpatiaLite
|
|
----------
|
|
|
|
.. note::
|
|
|
|
Mac OS X users should follow the instructions in the :ref:`kyngchaos` section,
|
|
as it is much easier than building from source.
|
|
|
|
`SpatiaLite`__ adds spatial support to SQLite, turning it into a full-featured
|
|
spatial database. Because SpatiaLite has special requirements, it typically
|
|
requires SQLite and pysqlite2 (the Python SQLite DB-API adaptor) to be built from
|
|
source. :ref:`geosbuild` and :ref:`proj4` should be installed prior to building
|
|
SpatiaLite.
|
|
|
|
After installation is complete, don't forget to read the post-installation
|
|
docs on :ref:`create_spatialite_db`.
|
|
|
|
__ http://www.gaia-gis.it/spatialite/index.html
|
|
|
|
.. _sqlite:
|
|
|
|
SQLite
|
|
^^^^^^
|
|
|
|
Typically, SQLite packages are not compiled to include the `R*Tree module`__ --
|
|
thus it must be compiled from source. First download the latest amalgamation
|
|
source archive from the `SQLite download page`__, and extract::
|
|
|
|
$ wget http://sqlite.org/sqlite-amalgamation-3.6.23.1.tar.gz
|
|
$ tar xzf sqlite-amalgamation-3.6.23.1.tar.gz
|
|
$ cd sqlite-3.6.23.1
|
|
|
|
Next, run the ``configure`` script -- however the ``CFLAGS`` environment variable
|
|
needs to be customized so that SQLite knows to build the R*Tree module::
|
|
|
|
$ CFLAGS="-DSQLITE_ENABLE_RTREE=1" ./configure
|
|
$ make
|
|
$ sudo make install
|
|
$ cd ..
|
|
|
|
.. note::
|
|
|
|
If using Ubuntu, installing a newer SQLite from source can be very difficult
|
|
because it links to the existing ``libsqlite3.so`` in ``/usr/lib`` which
|
|
many other packages depend on. Unfortunately, the best solution at this time
|
|
is to overwrite the existing library by adding ``--prefix=/usr`` to the
|
|
``configure`` command.
|
|
|
|
__ http://www.sqlite.org/rtree.html
|
|
__ http://www.sqlite.org/download.html
|
|
|
|
.. _spatialitebuild :
|
|
|
|
SpatiaLite Library (``libspatialite``) and Tools (``spatialite``)
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
After SQLite has been built with the R*Tree module enabled, get the latest
|
|
SpatiaLite library source and tools bundle from the `download page`__::
|
|
|
|
$ wget http://www.gaia-gis.it/spatialite/libspatialite-amalgamation-2.3.1.tar.gz
|
|
$ wget http://www.gaia-gis.it/spatialite/spatialite-tools-2.3.1.tar.gz
|
|
$ tar xzf libspatialite-amalgamation-2.3.1.tar.gz
|
|
$ tar xzf spatialite-tools-2.3.1.tar.gz
|
|
|
|
Prior to attempting to build, please read the important notes below to see if
|
|
customization of the ``configure`` command is necessary. If not, then run the
|
|
``configure`` script, make, and install for the SpatiaLite library::
|
|
|
|
$ cd libspatialite-amalgamation-2.3.1
|
|
$ ./configure # May need to modified, see notes below.
|
|
$ make
|
|
$ sudo make install
|
|
$ cd ..
|
|
|
|
Finally, do the same for the SpatiaLite tools::
|
|
|
|
$ cd spatialite-tools-2.3.1
|
|
$ ./configure # May need to modified, see notes below.
|
|
$ make
|
|
$ sudo make install
|
|
$ cd ..
|
|
|
|
.. note::
|
|
|
|
If you've installed GEOS and PROJ.4 from binary packages, you will have to specify
|
|
their paths when running the ``configure`` scripts for *both* the library and the
|
|
tools (the configure scripts look, by default, in ``/usr/local``). For example,
|
|
on Debian/Ubuntu distributions that have GEOS and PROJ.4 packages, the command would be::
|
|
|
|
$ ./configure --with-proj-include=/usr/include --with-proj-lib=/usr/lib --with-geos-include=/usr/include --with-geos-lib=/usr/lib
|
|
|
|
.. note::
|
|
|
|
For Mac OS X users building from source, the SpatiaLite library *and* tools
|
|
need to have their ``target`` configured::
|
|
|
|
$ ./configure --target=macosx
|
|
|
|
__ http://www.gaia-gis.it/spatialite/sources.html
|
|
|
|
.. _pysqlite2:
|
|
|
|
pysqlite2
|
|
^^^^^^^^^
|
|
|
|
Because SpatiaLite must be loaded as an external extension, it requires the
|
|
``enable_load_extension`` method, which is only available in versions 2.5+.
|
|
Thus, download pysqlite2 2.6, and untar::
|
|
|
|
$ wget http://pysqlite.googlecode.com/files/pysqlite-2.6.0.tar.gz
|
|
$ tar xzf pysqlite-2.6.0.tar.gz
|
|
$ cd pysqlite-2.6.0
|
|
|
|
Next, use a text editor (e.g., ``emacs`` or ``vi``) to edit the ``setup.cfg`` file
|
|
to look like the following::
|
|
|
|
[build_ext]
|
|
#define=
|
|
include_dirs=/usr/local/include
|
|
library_dirs=/usr/local/lib
|
|
libraries=sqlite3
|
|
#define=SQLITE_OMIT_LOAD_EXTENSION
|
|
|
|
.. note::
|
|
|
|
The important thing here is to make sure you comment out the
|
|
``define=SQLITE_OMIT_LOAD_EXTENSION`` flag and that the ``include_dirs``
|
|
and ``library_dirs`` settings are uncommented and set to the appropriate
|
|
path if the SQLite header files and libraries are not in ``/usr/include``
|
|
and ``/usr/lib``, respectively.
|
|
|
|
After modifying ``setup.cfg`` appropriately, then run the ``setup.py`` script
|
|
to build and install::
|
|
|
|
$ sudo python setup.py install
|
|
|
|
Post-Installation
|
|
=================
|
|
|
|
.. _spatialdb_template:
|
|
|
|
Creating a Spatial Database Template for PostGIS
|
|
------------------------------------------------
|
|
|
|
Creating a spatial database with PostGIS is different than normal because
|
|
additional SQL must be loaded to enable spatial functionality. Because of
|
|
the steps in this process, it's better to create a database template that
|
|
can be reused later.
|
|
|
|
First, you need to be able to execute the commands as a privileged database
|
|
user. For example, you can use the following to become the ``postgres`` user::
|
|
|
|
$ sudo su - postgres
|
|
|
|
.. note::
|
|
|
|
The location *and* name of the PostGIS SQL files (e.g., from
|
|
``POSTGIS_SQL_PATH`` below) depends on the version of PostGIS.
|
|
PostGIS versions 1.3 and below use ``<pg_sharedir>/contrib/lwpostgis.sql``;
|
|
whereas version 1.4 uses ``<sharedir>/contrib/postgis.sql`` and
|
|
version 1.5 uses ``<sharedir>/contrib/postgis-1.5/postgis.sql``.
|
|
|
|
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-1.5
|
|
# Creating the template spatial database.
|
|
$ createdb -E UTF8 template_postgis
|
|
$ createlang -d template_postgis plpgsql # Adding PLPGSQL language support.
|
|
# Allows non-superusers the ability to create from this template
|
|
$ psql -d postgres -c "UPDATE pg_database SET datistemplate='true' WHERE datname='template_postgis';"
|
|
# Loading the PostGIS SQL routines
|
|
$ psql -d template_postgis -f $POSTGIS_SQL_PATH/postgis.sql
|
|
$ psql -d template_postgis -f $POSTGIS_SQL_PATH/spatial_ref_sys.sql
|
|
# Enabling users to alter spatial tables.
|
|
$ psql -d template_postgis -c "GRANT ALL ON geometry_columns TO PUBLIC;"
|
|
$ psql -d template_postgis -c "GRANT ALL ON geography_columns TO PUBLIC;"
|
|
$ psql -d template_postgis -c "GRANT ALL ON spatial_ref_sys TO PUBLIC;"
|
|
|
|
These commands may be placed in a shell script for later use; for convenience
|
|
the following scripts are available:
|
|
|
|
=============== =============================================
|
|
PostGIS Version 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 the SpatiaLite library and tools have been installed, it is now possible
|
|
to create spatial database for use with GeoDjango. In order to do this, download
|
|
the spatial database initialization SQL from the `SpatiaLite Resources`__ page::
|
|
|
|
$ wget http://www.gaia-gis.it/spatialite/init_spatialite-2.3.sql.gz
|
|
$ gunzip init_spatialite-2.3.sql.gz
|
|
|
|
Now, the ``spatialite`` command can be used to initialize a spatial database::
|
|
|
|
$ spatialite geodjango.db < init_spatialite-2.3.sql
|
|
|
|
.. note::
|
|
|
|
The parameter ``geodjango.db`` is the *filename* of the SQLite database
|
|
you want to use. Use the same in the :setting:`DATABASES` ``"name"`` key
|
|
inside your ``settings.py``.
|
|
|
|
|
|
__ http://www.gaia-gis.it/spatialite/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
|
|
--------------------------------------------------
|
|
|
|
.. versionchanged:: 1.2
|
|
|
|
.. note::
|
|
|
|
If running PostGIS 1.4 and above, the entry is already included in the
|
|
default ``spatial_ref_sys`` table. You can skip this step.
|
|
|
|
In order to conduct database transformations to the so-called "Google"
|
|
projection (a spherical mercator projection used by Google Maps),
|
|
an entry must be added to your spatial database's ``spatial_ref_sys`` table.
|
|
Invoke the Django shell from your project and execute the
|
|
``add_srs_entry`` function::
|
|
|
|
$ python manage shell
|
|
>>> from django.contrib.gis.utils import add_srs_entry
|
|
>>> add_srs_entry(900913)
|
|
|
|
.. note::
|
|
|
|
In Django 1.1 the name of this function is ``add_postgis_srs``.
|
|
|
|
This adds an entry for the 900913 SRID to the ``spatial_ref_sys`` (or equivalent)
|
|
table, making it possible for the spatial database to transform coordinates in
|
|
this projection. You only need to execute this command *once* per spatial database.
|
|
|
|
Troubleshooting
|
|
===============
|
|
|
|
If you can't find the solution to your problem here then participate in the
|
|
community! You can:
|
|
|
|
* Join the ``#geodjango`` IRC channel on FreeNode (may be accessed on the
|
|
Web via `Mibbit`__). Please be patient and polite -- while you may not
|
|
get an immediate response, someone will attempt to answer your question
|
|
as soon as they see it.
|
|
* Ask your question on the `GeoDjango`__ mailing list.
|
|
* File a ticket on the `Django trac`__ if you think there's a bug. Make
|
|
sure to provide a complete description of the problem, versions used,
|
|
and specify the component as "GIS".
|
|
|
|
__ http://www.mibbit.com/?server=irc.freenode.net&channel=%23geodjango
|
|
__ http://groups.google.com/group/geodjango
|
|
__ http://code.djangoproject.com/simpleticket
|
|
|
|
.. _libsettings:
|
|
|
|
Library Environment Settings
|
|
----------------------------
|
|
|
|
By far, the most common problem when installing GeoDjango is that the
|
|
external shared libraries (e.g., for GEOS and GDAL) cannot be located. [#]_
|
|
Typically, the cause of this problem is that the operating system isn't aware
|
|
of the directory where the libraries built from source were installed.
|
|
|
|
In general, the library path may be set on a per-user basis by setting
|
|
an environment variable, or by configuring the library path for the entire
|
|
system.
|
|
|
|
``LD_LIBRARY_PATH`` environment variable
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
A user may set this environment variable to customize the library paths
|
|
they want to use. The typical library directory for software
|
|
built from source is ``/usr/local/lib``. Thus, ``/usr/local/lib`` needs
|
|
to be included in the ``LD_LIBRARY_PATH`` variable. For example, the user
|
|
could place the following in their bash profile::
|
|
|
|
export LD_LIBRARY_PATH=/usr/local/lib
|
|
|
|
Setting System Library Path
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
On GNU/Linux systems, there is typically a file in ``/etc/ld.so.conf``, which may include
|
|
additional paths from files in another directory, such as ``/etc/ld.so.conf.d``.
|
|
As the root user, add the custom library path (like ``/usr/local/lib``) on a
|
|
new line in ``ld.so.conf``. This is *one* example of how to do so::
|
|
|
|
$ sudo echo /usr/local/lib >> /etc/ld.so.conf
|
|
$ sudo ldconfig
|
|
|
|
For OpenSolaris users, the system library path may be modified using the
|
|
``crle`` utility. Run ``crle`` with no options to see the current configuration
|
|
and use ``crle -l`` to set with the new library path. Be *very* careful when
|
|
modifying the system library path::
|
|
|
|
# crle -l $OLD_PATH:/usr/local/lib
|
|
|
|
.. _binutils:
|
|
|
|
Install ``binutils``
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
GeoDjango uses the ``find_library`` function (from the ``ctypes.util`` Python
|
|
module) to discover libraries. The ``find_library`` routine uses a program
|
|
called ``objdump`` (part of the ``binutils`` package) to verify a shared
|
|
library on GNU/Linux systems. Thus, if ``binutils`` is not installed on your
|
|
Linux system then Python's ctypes may not be able to find your library even if
|
|
your library path is set correctly and geospatial libraries were built perfectly.
|
|
|
|
The ``binutils`` package may be installed on Debian and Ubuntu systems using the
|
|
following command::
|
|
|
|
$ sudo apt-get install binutils
|
|
|
|
Similarly, on Red Hat and CentOS systems::
|
|
|
|
$ sudo yum install binutils
|
|
|
|
Platform Specific Instructions
|
|
==============================
|
|
|
|
.. _macosx:
|
|
|
|
Mac OS X
|
|
--------
|
|
|
|
Because of the variety of packaging systems available for OS X, users have
|
|
several different options for installing GeoDjango. These options are:
|
|
|
|
* :ref:`kyngchaos`
|
|
* :ref:`fink`
|
|
* :ref:`macports`
|
|
* :ref:`build_from_source`
|
|
|
|
.. note::
|
|
|
|
Currently, the easiest and recommended approach for installing GeoDjango
|
|
on OS X is to use the KyngChaos packages.
|
|
|
|
This section also includes instructions for installing an upgraded version
|
|
of :ref:`macosx_python` from packages provided by the Python Software
|
|
Foundation, however, this is not required.
|
|
|
|
.. _macosx_python:
|
|
|
|
Python
|
|
^^^^^^
|
|
|
|
Although OS X comes with Python installed, users can use framework
|
|
installers (`2.5`__ and `2.6`__ are available) provided by
|
|
the Python Software Foundation. An advantage to using the installer is
|
|
that OS X's Python will remain "pristine" for internal operating system
|
|
use.
|
|
|
|
__ http://python.org/ftp/python/2.5.4/python-2.5.4-macosx.dmg
|
|
__ http://python.org/ftp/python/2.6.2/python-2.6.2-macosx2009-04-16.dmg
|
|
|
|
.. note::
|
|
|
|
You will need to modify the ``PATH`` environment variable in your
|
|
``.profile`` file so that the new version of Python is used when
|
|
``python`` is entered at the command-line::
|
|
|
|
export PATH=/Library/Frameworks/Python.framework/Versions/Current/bin:$PATH
|
|
|
|
.. _kyngchaos:
|
|
|
|
KyngChaos Packages
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
William Kyngesburye provides a number of `geospatial library binary packages`__
|
|
that make it simple to get GeoDjango installed on OS X without compiling
|
|
them from source. However, the `Apple Developer Tools`_ are still necessary
|
|
for compiling the Python database adapters :ref:`psycopg2_kyngchaos` (for PostGIS)
|
|
and :ref:`pysqlite2_kyngchaos` (for SpatiaLite).
|
|
|
|
.. note::
|
|
|
|
SpatiaLite users should consult the :ref:`spatialite_kyngchaos` section
|
|
after installing the packages for additional instructions.
|
|
|
|
Download the framework packages for:
|
|
|
|
* UnixImageIO
|
|
* PROJ
|
|
* GEOS
|
|
* SQLite3 (includes the SpatiaLite library)
|
|
* GDAL
|
|
|
|
Install the packages in the order they are listed above, as the GDAL and SQLite
|
|
packages require the packages listed before them. Afterwards, you can also
|
|
install the KyngChaos binary packages for `PostgreSQL and PostGIS`__.
|
|
|
|
After installing the binary packages, you'll want to add the following to
|
|
your ``.profile`` to be able to run the package programs from the command-line::
|
|
|
|
export PATH=/Library/Frameworks/UnixImageIO.framework/Programs:$PATH
|
|
export PATH=/Library/Frameworks/PROJ.framework/Programs:$PATH
|
|
export PATH=/Library/Frameworks/GEOS.framework/Programs:$PATH
|
|
export PATH=/Library/Frameworks/SQLite3.framework/Programs:$PATH
|
|
export PATH=/Library/Frameworks/GDAL.framework/Programs:$PATH
|
|
export PATH=/usr/local/pgsql/bin:$PATH
|
|
|
|
__ http://www.kyngchaos.com/software/frameworks
|
|
__ http://www.kyngchaos.com/software/postgres
|
|
|
|
.. note::
|
|
|
|
Use of these binaries requires Django 1.0.3 and above. If you are
|
|
using a previous version of Django (like 1.0.2), then you will have
|
|
to add the following in your settings::
|
|
|
|
GEOS_LIBRARY_PATH='/Library/Frameworks/GEOS.framework/GEOS'
|
|
GDAL_LIBRARY_PATH='/Library/Frameworks/GDAL.framework/GDAL'
|
|
|
|
.. _psycopg2_kyngchaos:
|
|
|
|
psycopg2
|
|
~~~~~~~~
|
|
|
|
After you've installed the KyngChaos binaries and modified your ``PATH``, as
|
|
described above, ``psycopg2`` may be installed using the following command::
|
|
|
|
$ sudo python easy_install psycopg2
|
|
|
|
.. note::
|
|
|
|
To use ``easy_install`` you'll need to install Python's `setuptools`_.
|
|
|
|
.. _setuptools: http://pypi.python.org/pypi/setuptools
|
|
|
|
.. _pysqlite2_kyngchaos:
|
|
|
|
pysqlite2
|
|
~~~~~~~~~
|
|
|
|
Follow the :ref:`pysqlite2` source install instructions, however,
|
|
when editing the ``setup.cfg`` use the following instead::
|
|
|
|
[build_ext]
|
|
#define=
|
|
include_dirs=/Library/Frameworks/SQLite3.framework/unix/include
|
|
library_dirs=/Library/Frameworks/SQLite3.framework/unix/lib
|
|
libraries=sqlite3
|
|
#define=SQLITE_OMIT_LOAD_EXTENSION
|
|
|
|
.. _spatialite_kyngchaos:
|
|
|
|
SpatiaLite
|
|
~~~~~~~~~~
|
|
|
|
When :ref:`create_spatialite_db`, the ``spatialite`` program is required.
|
|
However, instead of attempting to compile the SpatiaLite tools from source,
|
|
download the `SpatiaLite Binaries`__ for OS X, and install ``spatialite`` in a
|
|
location available in your ``PATH``. For example::
|
|
|
|
$ curl -O http://www.gaia-gis.it/spatialite/spatialite-tools-osx-x86-2.3.1.tar.gz
|
|
$ tar xzf spatialite-tools-osx-x86-2.3.1.tar.gz
|
|
$ cd spatialite-tools-osx-x86-2.3.1/bin
|
|
$ sudo cp spatialite /Library/Frameworks/SQLite3.framework/Programs
|
|
|
|
Finally, for GeoDjango to be able to find the KyngChaos SpatiaLite library,
|
|
add the following to your ``settings.py``::
|
|
|
|
SPATIALITE_LIBRARY_PATH='/Library/Frameworks/SQLite3.framework/SQLite3'
|
|
|
|
__ http://www.gaia-gis.it/spatialite/binaries.html
|
|
|
|
.. _fink:
|
|
|
|
Fink
|
|
^^^^
|
|
|
|
`Kurt Schwehr`__ has been gracious enough to create GeoDjango packages for users
|
|
of the `Fink`__ package system. The following packages are available, depending
|
|
on which version of Python you want to use:
|
|
|
|
* ``django-gis-py26``
|
|
* ``django-gis-py25``
|
|
* ``django-gis-py24``
|
|
|
|
__ http://schwehr.org/blog/
|
|
__ http://www.finkproject.org/
|
|
|
|
.. _macports:
|
|
|
|
MacPorts
|
|
^^^^^^^^
|
|
|
|
`MacPorts`__ may be used to install GeoDjango prerequisites on Macintosh
|
|
computers running OS X. Because MacPorts still builds the software from source,
|
|
the `Apple Developer Tools`_ are required.
|
|
|
|
Summary::
|
|
|
|
$ sudo port install postgresql83-server
|
|
$ sudo port install geos
|
|
$ sudo port install proj
|
|
$ sudo port install postgis
|
|
$ sudo port install gdal
|
|
$ sudo port install libgeoip
|
|
|
|
.. note::
|
|
|
|
You will also have to modify the ``PATH`` in your ``.profile`` so
|
|
that the MacPorts programs are accessible from the command-line::
|
|
|
|
export PATH=/opt/local/bin:/opt/local/lib/postgresql83/bin
|
|
|
|
In addition, add the ``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 the PostgreSQL share directory in the
|
|
Debian and Ubuntu packages, and are located instead special directory
|
|
depending on the release. Thus, when :ref:`spatialdb_template` use the
|
|
:download:`create_template_postgis-debian.sh` script instead
|
|
|
|
.. _ubuntu:
|
|
|
|
Ubuntu
|
|
^^^^^^
|
|
|
|
.. _ubuntu10:
|
|
|
|
10.04 and 10.10
|
|
~~~~~~~~~~~~~~~
|
|
|
|
In Ubuntu 10 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 commands are::
|
|
|
|
$ sudo apt-get install binutils gdal-bin postgresql-8.4-postgis \
|
|
postgresql-server-dev-8.4 python-psycopg2 python-setuptools
|
|
$ sudo easy_install Django
|
|
|
|
.. _ibex:
|
|
|
|
8.10
|
|
~~~~
|
|
|
|
Use the synaptic package manager to install the following packages::
|
|
|
|
$ sudo apt-get install binutils gdal-bin postgresql-8.3-postgis \
|
|
postgresql-server-dev-8.3 python-psycopg2 python-setuptools
|
|
|
|
Afterwards, you may install Django with Python's ``easy_install`` script (the
|
|
Ubuntu package ``python-django`` uses an older version missing several
|
|
important bug fixes for GeoDjango)::
|
|
|
|
$ sudo easy_install Django
|
|
|
|
That's it! For the curious, the required binary prerequisites packages are:
|
|
|
|
* ``binutils``: for ctypes to find libraries
|
|
* ``postgresql-8.3``
|
|
* ``postgresql-server-dev-8.3``: for ``pg_config``
|
|
* ``postgresql-8.3-postgis``: for PostGIS 1.3.3
|
|
* ``libgeos-3.0.0``, and ``libgeos-c1``: for GEOS 3.0.0
|
|
* ``libgdal1-1.5.0``: for GDAL 1.5.0 library
|
|
* ``proj``: for PROJ 4.6.0 -- but no datum shifting files, see note below
|
|
* ``python-psycopg2``
|
|
* ``python-setuptools``: for ``easy_install``
|
|
|
|
Optional packages to consider:
|
|
|
|
* ``libgeoip1``: for :ref:`GeoIP <ref-geoip>` support
|
|
* ``gdal-bin``: for GDAL command line programs like ``ogr2ogr``
|
|
* ``python-gdal`` for GDAL's own Python bindings -- includes interfaces for raster manipulation
|
|
|
|
.. note::
|
|
|
|
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::
|
|
|
|
$ 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).
|
|
|
|
.. _heron:
|
|
|
|
8.04 and lower
|
|
~~~~~~~~~~~~~~
|
|
|
|
The 8.04 (and lower) versions of Ubuntu use GEOS v2.2.3 in their binary packages,
|
|
which is incompatible with GeoDjango. Thus, do *not* use the binary packages
|
|
for GEOS or PostGIS and build some prerequisites from source, per the instructions
|
|
in this document; however, it is okay to use the PostgreSQL binary packages.
|
|
|
|
For more details, please see the Debian instructions for :ref:`etch` below.
|
|
|
|
.. _debian:
|
|
|
|
Debian
|
|
------
|
|
|
|
.. _etch:
|
|
|
|
4.0 (Etch)
|
|
^^^^^^^^^^
|
|
The situation here is the same as that of Ubuntu :ref:`heron` -- in other words,
|
|
some packages must be built from source to work properly with GeoDjango.
|
|
|
|
Binary Packages
|
|
~~~~~~~~~~~~~~~
|
|
The following command will install acceptable binary packages, as well as
|
|
the development tools necessary to build the rest of the requirements::
|
|
|
|
$ sudo apt-get install binutils bzip2 gcc g++ flex make postgresql-8.1 postgresql-server-dev-8.1 python-ctypes python-psycopg2 python-setuptools
|
|
|
|
Required package information:
|
|
|
|
* ``binutils``: for ctypes to find libraries
|
|
* ``bzip2``: for decompressing the source packages
|
|
* ``gcc``, ``g++``, ``make``: GNU developer tools used to compile the libraries
|
|
* ``flex``: required to build PostGIS
|
|
* ``postgresql-8.1``
|
|
* ``postgresql-server-dev-8.1``: for ``pg_config``
|
|
* ``python-psycopg2``
|
|
* ``python-setuptools``: for ``easy_install``
|
|
|
|
Optional packages:
|
|
|
|
* ``libgeoip``: for :ref:`GeoIP <ref-geoip>` support
|
|
|
|
Source Packages
|
|
~~~~~~~~~~~~~~~
|
|
You will still have to install :ref:`geosbuild`, :ref:`proj4`,
|
|
:ref:`postgis`, and :ref:`gdalbuild` from source. Please follow the
|
|
directions carefully.
|
|
|
|
.. _lenny:
|
|
|
|
5.0 (Lenny)
|
|
^^^^^^^^^^^
|
|
|
|
This version is comparable to Ubuntu :ref:`ibex`, so the command
|
|
is very similar::
|
|
|
|
$ sudo apt-get install binutils libgdal1-1.5.0 postgresql-8.3 postgresql-8.3-postgis postgresql-server-dev-8.3 python-psycopg2 python-setuptools
|
|
|
|
This assumes that you are using PostgreSQL version 8.3. Else, replace ``8.3``
|
|
in the above command with the appropriate PostgreSQL version.
|
|
|
|
.. note::
|
|
|
|
Please read the note in the Ubuntu :ref:`ibex` install documentation
|
|
about the ``proj`` package -- it also applies here because the package does
|
|
not include the datum shifting files.
|
|
|
|
.. _post_install:
|
|
|
|
Post-installation Notes
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
If the PostgreSQL database cluster was not initiated after installing, then it
|
|
can be created (and started) with the following command::
|
|
|
|
$ sudo pg_createcluster --start 8.3 main
|
|
|
|
Afterwards, the ``/etc/init.d/postgresql-8.3`` script should be used to manage
|
|
the starting and stopping of PostgreSQL.
|
|
|
|
In addition, the SQL files for PostGIS are placed in a different location on
|
|
Debian 5.0 . Thus when :ref:`spatialdb_template` either:
|
|
|
|
* Create a symbolic link to these files::
|
|
|
|
$ sudo ln -s /usr/share/postgresql-8.3-postgis/{lwpostgis,spatial_ref_sys}.sql /usr/share/postgresql/8.3
|
|
|
|
If not running PostgreSQL 8.3, then replace ``8.3`` in the command above with the correct version.
|
|
|
|
* Or use the :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::
|
|
|
|
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 Setup 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)
|
|
<http://spatialreference.org/ref/epsg/900913/proj4>`_ requires the
|
|
``null`` grid file only included in the extra datum shifting files.
|
|
It is easier to install the shifting files now, then to have debug a
|
|
problem caused by their absence later.
|
|
.. [#] Specifically, GeoDjango provides support for the `OGR
|
|
<http://gdal.org/ogr>`_ library, a component of GDAL.
|
|
.. [#] See `GDAL ticket #2382 <http://trac.osgeo.org/gdal/ticket/2382>`_.
|
|
.. [#] GeoDjango uses the :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/>`_.
|