PageRenderTime 205ms CodeModel.GetById 101ms app.highlight 32ms RepoModel.GetById 18ms app.codeStats 1ms

/docs/ref/contrib/gis/install.txt

https://code.google.com/p/mango-py/
Plain Text | 1260 lines | 881 code | 379 blank | 0 comment | 0 complexity | f28278a5656eebcf810e6ef5d53fc7d3 MD5 | raw file
   1.. _ref-gis-install:
   2
   3======================
   4GeoDjango Installation
   5======================
   6
   7Overview
   8========
   9In general, GeoDjango installation requires:
  10
  111. :ref:`python24` and :ref:`django`
  122. :ref:`spatial_database`
  133. :ref:`geospatial_libs`
  14
  15Details for each of the requirements and installation instructions
  16are provided in the sections below.   In addition, platform-specific
  17instructions are available for:
  18
  19* :ref:`macosx`
  20* :ref:`ubuntudebian`
  21* :ref:`windows`
  22
  23.. admonition:: Use the Source
  24
  25    Because GeoDjango takes advantage of the latest in the open source geospatial
  26    software technology, recent versions of the libraries are necessary.
  27    If binary packages aren't available for your platform,
  28    :ref:`installation from source <build_from_source>`
  29    may be required. When compiling the libraries from source, please follow the
  30    directions closely, especially if you're a beginner.
  31
  32Requirements
  33============
  34
  35.. _python24:
  36
  37Python 2.4+
  38-----------
  39
  40Python 2.4 is the minimum version supported by Django, however Python 2.5+ is
  41recommended because the `ctypes`__ module comes included; otherwise, 2.4 users
  42will need to `download and install ctypes`__.
  43
  44__ http://docs.python.org/lib/module-ctypes.html
  45__ http://sourceforge.net/projects/ctypes/files/
  46
  47.. _django:
  48
  49Django
  50------
  51
  52Because GeoDjango is included with Django, please refer to Django's
  53:doc:`installation instructions </intro/install>` for details on how to install.
  54
  55.. _spatial_database:
  56
  57Spatial Database
  58----------------
  59PostgreSQL (with PostGIS), MySQL, Oracle, and SQLite (with SpatiaLite) are
  60the spatial databases currently supported.
  61
  62.. note::
  63
  64    PostGIS is recommended, because it is the most mature and feature-rich
  65    open source spatial database.
  66
  67The geospatial libraries required for a GeoDjango installation depends
  68on the spatial database used.  The following lists the library requirements,
  69supported versions, and any notes for each of the supported database backends:
  70
  71==================  ==============================  ==================  ==========================================================
  72Database            Library Requirements            Supported Versions  Notes
  73==================  ==============================  ==================  ==========================================================
  74PostgreSQL          GEOS, PROJ.4, PostGIS           8.1+                Requires PostGIS.
  75MySQL               GEOS                            5.x                 Not OGC-compliant; limited functionality.
  76Oracle              GEOS                            10.2, 11            XE not supported; not tested with 9.
  77SQLite              GEOS, GDAL, PROJ.4, SpatiaLite  3.6.+               Requires SpatiaLite 2.3+, pysqlite2 2.5+, and Django 1.1.
  78==================  ==============================  ==================  ==========================================================
  79
  80.. _geospatial_libs:
  81
  82Geospatial Libraries
  83--------------------
  84GeoDjango uses and/or provides interfaces for the following open source
  85geospatial libraries:
  86
  87========================  ====================================  ================================  ==========================
  88Program                   Description                           Required                          Supported Versions
  89========================  ====================================  ================================  ==========================
  90:ref:`GEOS <ref-geos>`    Geometry Engine Open Source           Yes                               3.2, 3.1, 3.0
  91`PROJ.4`_                 Cartographic Projections library      Yes (PostgreSQL and SQLite only)  4.7, 4.6, 4.5, 4.4
  92:ref:`GDAL <ref-gdal>`    Geospatial Data Abstraction Library   No (but, required for SQLite)     1.8, 1.7, 1.6, 1.5, 1.4
  93:ref:`GeoIP <ref-geoip>`  IP-based geolocation library          No                                1.4
  94`PostGIS`__               Spatial extensions for PostgreSQL     Yes (PostgreSQL only)             1.5, 1.4, 1.3
  95`SpatiaLite`__            Spatial extensions for SQLite         Yes (SQLite only)                 2.4, 2.3
  96========================  ====================================  ================================  ==========================
  97
  98.. admonition::  Install GDAL
  99
 100    While :ref:`gdalbuild` is technically not required, it is *recommended*.
 101    Important features of GeoDjango (including the :ref:`ref-layermapping`,
 102    geometry reprojection, and the geographic admin) depend on its
 103    functionality.
 104
 105.. note::
 106
 107    The GeoDjango interfaces to GEOS, GDAL, and GeoIP may be used
 108    independently of Django.  In other words, no database or settings file
 109    required -- just import them as normal from :mod:`django.contrib.gis`.
 110
 111.. _PROJ.4: http://trac.osgeo.org/proj/
 112__ http://postgis.refractions.net/
 113__ http://www.gaia-gis.it/spatialite/index.html
 114
 115.. _build_from_source:
 116
 117Building from Source
 118====================
 119
 120When installing from source on UNIX and GNU/Linux systems, please follow
 121the installation instructions carefully, and install the libraries in the
 122given order.  If using MySQL or Oracle as the spatial database, only GEOS
 123is required.
 124
 125.. note::
 126
 127   On Linux platforms, it may be necessarry to run the ``ldconfig``
 128   command after installing each library.  For example::
 129
 130       $ sudo make install
 131       $ sudo ldconfig
 132
 133.. note::
 134
 135    OS X users are required to install `Apple Developer Tools`_ in order
 136    to compile software from source.  This is typically included on your
 137    OS X installation DVDs.
 138
 139.. _Apple Developer Tools: http://developer.apple.com/tools/xcode/
 140
 141.. _geosbuild:
 142
 143GEOS
 144----
 145
 146GEOS is a C++ library for performing geometric operations, and is the default
 147internal geometry representation used by GeoDjango (it's behind the "lazy"
 148geometries).  Specifically, the C API library is called (e.g., ``libgeos_c.so``)
 149directly from Python using ctypes.
 150
 151First, download GEOS 3.2 from the refractions Web site and untar the source
 152archive::
 153
 154    $ wget http://download.osgeo.org/geos/geos-3.2.2.tar.bz2
 155    $ tar xjf geos-3.2.2.tar.bz2
 156
 157Next, change into the directory where GEOS was unpacked, run the configure
 158script, compile, and install::
 159
 160    $ cd geos-3.2.2
 161    $ ./configure
 162    $ make
 163    $ sudo make install
 164    $ cd ..
 165
 166Troubleshooting
 167^^^^^^^^^^^^^^^
 168
 169Can't find GEOS Library
 170~~~~~~~~~~~~~~~~~~~~~~~
 171
 172When GeoDjango can't find GEOS, this error is raised::
 173
 174    ImportError: Could not find the GEOS library (tried "geos_c"). Try setting GEOS_LIBRARY_PATH in your settings.
 175
 176The most common solution is to properly configure your :ref:`libsettings` *or* set
 177:ref:`geoslibrarypath` in your settings.
 178
 179If using a binary package of GEOS (e.g., on Ubuntu), you may need to :ref:`binutils`.
 180
 181.. _geoslibrarypath:
 182
 183``GEOS_LIBRARY_PATH``
 184~~~~~~~~~~~~~~~~~~~~~
 185
 186If your GEOS library is in a non-standard location, or you don't want to
 187modify the system's library path then the :setting:`GEOS_LIBRARY_PATH`
 188setting may be added to your Django settings file with the full path to the
 189GEOS C library.  For example::
 190
 191    GEOS_LIBRARY_PATH = '/home/bob/local/lib/libgeos_c.so'
 192
 193.. note::
 194
 195    The setting must be the *full* path to the **C** shared library; in
 196    other words you want to use ``libgeos_c.so``, not ``libgeos.so``.
 197
 198.. _proj4:
 199
 200PROJ.4
 201------
 202
 203`PROJ.4`_ is a library for converting geospatial data to different coordinate
 204reference systems.
 205
 206First, download the PROJ.4 source code and datum shifting files [#]_::
 207
 208    $ wget http://download.osgeo.org/proj/proj-4.7.0.tar.gz
 209    $ wget http://download.osgeo.org/proj/proj-datumgrid-1.5.zip
 210
 211Next, untar the source code archive, and extract the datum shifting files in the
 212``nad`` subdirectory.  This must be done *prior* to configuration::
 213
 214    $ tar xzf proj-4.7.0.tar.gz
 215    $ cd proj-4.7.0/nad
 216    $ unzip ../../proj-datumgrid-1.5.zip
 217    $ cd ..
 218
 219Finally, configure, make and install PROJ.4::
 220
 221    $ ./configure
 222    $ make
 223    $ sudo make install
 224    $ cd ..
 225
 226.. _postgis:
 227
 228PostGIS
 229-------
 230
 231`PostGIS`__ adds geographic object support to PostgreSQL, turning it
 232into a spatial database. :ref:`geosbuild` and :ref:`proj4` should be
 233installed prior to building PostGIS.
 234
 235.. note::
 236
 237    The `psycopg2`_ module is required for use as the database adaptor
 238    when using GeoDjango with PostGIS.
 239
 240.. _psycopg2: http://initd.org/projects/psycopg2
 241
 242First download the source archive, and extract::
 243
 244    $ wget http://postgis.refractions.net/download/postgis-1.5.2.tar.gz
 245    $ tar xzf postgis-1.5.2.tar.gz
 246    $ cd postgis-1.5.2
 247
 248Next, configure, make and install PostGIS::
 249
 250    $ ./configure
 251
 252Finally, make and install::
 253
 254    $ make
 255    $ sudo make install
 256    $ cd ..
 257
 258.. note::
 259
 260    GeoDjango does not automatically create a spatial database.  Please
 261    consult the section on :ref:`spatialdb_template` for more information.
 262
 263__ http://postgis.refractions.net/
 264
 265.. _gdalbuild:
 266
 267GDAL
 268----
 269
 270`GDAL`__ is an excellent open source geospatial library that has support for
 271reading most vector and raster spatial data formats.  Currently, GeoDjango only
 272supports :ref:`GDAL's vector data <ref-gdal>` capabilities [#]_.
 273:ref:`geosbuild` and :ref:`proj4` should be installed prior to building GDAL.
 274
 275First download the latest GDAL release version and untar the archive::
 276
 277    $ wget http://download.osgeo.org/gdal/gdal-1.8.0.tar.gz
 278    $ tar xzf gdal-1.8.0.tar.gz
 279    $ cd gdal-1.8.0
 280
 281Configure, make and install::
 282
 283    $ ./configure
 284    $ make # Go get some coffee, this takes a while.
 285    $ sudo make install
 286    $ cd ..
 287
 288.. note::
 289
 290   Because GeoDjango has it's own Python interface, the preceding instructions
 291   do not build GDAL's own Python bindings.  The bindings may be built by
 292   adding the ``--with-python`` flag when running ``configure``.  See
 293   `GDAL/OGR In Python`__ for more information on GDAL's bindings.
 294
 295If you have any problems, please see the troubleshooting section below for
 296suggestions and solutions.
 297
 298__ http://trac.osgeo.org/gdal/
 299__ http://trac.osgeo.org/gdal/wiki/GdalOgrInPython
 300
 301.. _gdaltrouble:
 302
 303Troubleshooting
 304^^^^^^^^^^^^^^^
 305
 306Can't find GDAL Library
 307~~~~~~~~~~~~~~~~~~~~~~~
 308
 309When GeoDjango can't find the GDAL library, the ``HAS_GDAL`` flag
 310will be false::
 311
 312    >>> from django.contrib.gis import gdal
 313    >>> gdal.HAS_GDAL
 314    False
 315
 316The solution is to properly configure your :ref:`libsettings` *or* set
 317:ref:`gdallibrarypath` in your settings.
 318
 319.. _gdallibrarypath:
 320
 321``GDAL_LIBRARY_PATH``
 322~~~~~~~~~~~~~~~~~~~~~
 323
 324If your GDAL library is in a non-standard location, or you don't want to
 325modify the system's library path then the :setting:`GDAL_LIBRARY_PATH`
 326setting may be added to your Django settings file with the full path to
 327the GDAL library.  For example::
 328
 329    GDAL_LIBRARY_PATH = '/home/sue/local/lib/libgdal.so'
 330
 331.. _gdaldata:
 332
 333Can't find GDAL data files (``GDAL_DATA``)
 334~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 335
 336When installed from source, GDAL versions 1.5.1 and below have an autoconf bug
 337that places data in the wrong location. [#]_   This can lead to error messages
 338like this::
 339
 340    ERROR 4: Unable to open EPSG support file gcs.csv.
 341    ...
 342    OGRException: OGR failure.
 343
 344The solution is to set the ``GDAL_DATA`` environment variable to the location of the
 345GDAL data files before invoking Python  (typically ``/usr/local/share``; use
 346``gdal-config --datadir`` to find out). For example::
 347
 348    $ export GDAL_DATA=`gdal-config --datadir`
 349    $ python manage.py shell
 350
 351If using Apache, you may need to add this environment variable to your configuration
 352file::
 353
 354    SetEnv GDAL_DATA /usr/local/share
 355
 356.. _spatialite:
 357
 358SpatiaLite
 359----------
 360
 361.. note::
 362
 363   Mac OS X users should follow the instructions in the :ref:`kyngchaos` section,
 364   as it is much easier than building from source.
 365
 366`SpatiaLite`__ adds spatial support to SQLite, turning it into a full-featured
 367spatial database.  Because SpatiaLite has special requirements, it typically
 368requires SQLite and pysqlite2 (the Python SQLite DB-API adaptor) to be built from
 369source.  :ref:`geosbuild` and :ref:`proj4` should be installed prior to building
 370SpatiaLite.
 371
 372After installation is complete, don't forget to read the post-installation
 373docs on :ref:`create_spatialite_db`.
 374
 375__ http://www.gaia-gis.it/spatialite/index.html
 376
 377.. _sqlite:
 378
 379SQLite
 380^^^^^^
 381
 382Typically, SQLite packages are not compiled to include the `R*Tree module`__ --
 383thus it must be compiled from source.  First download the latest amalgamation
 384source archive from the `SQLite download page`__, and extract::
 385
 386    $ wget http://sqlite.org/sqlite-amalgamation-3.6.23.1.tar.gz
 387    $ tar xzf sqlite-amalgamation-3.6.23.1.tar.gz
 388    $ cd sqlite-3.6.23.1
 389
 390Next, run the ``configure`` script -- however the ``CFLAGS`` environment variable
 391needs to be customized so that SQLite knows to build the R*Tree module::
 392
 393    $ CFLAGS="-DSQLITE_ENABLE_RTREE=1" ./configure
 394    $ make
 395    $ sudo make install
 396    $ cd ..
 397
 398.. note::
 399
 400    If using Ubuntu, installing a newer SQLite from source can be very difficult
 401    because it links to the existing ``libsqlite3.so`` in ``/usr/lib`` which
 402    many other packages depend on.  Unfortunately, the best solution at this time
 403    is to overwrite the existing library by adding ``--prefix=/usr`` to the
 404    ``configure`` command.
 405
 406__ http://www.sqlite.org/rtree.html
 407__ http://www.sqlite.org/download.html
 408
 409.. _spatialitebuild :
 410
 411SpatiaLite Library (``libspatialite``) and Tools (``spatialite``)
 412^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 413
 414After SQLite has been built with the R*Tree module enabled, get the latest
 415SpatiaLite library source and tools bundle from the `download page`__::
 416
 417    $ wget http://www.gaia-gis.it/spatialite/libspatialite-amalgamation-2.3.1.tar.gz
 418    $ wget http://www.gaia-gis.it/spatialite/spatialite-tools-2.3.1.tar.gz
 419    $ tar xzf libspatialite-amalgamation-2.3.1.tar.gz
 420    $ tar xzf spatialite-tools-2.3.1.tar.gz
 421
 422Prior to attempting to build, please read the important notes below to see if
 423customization of the ``configure`` command is necessary.  If not, then run the
 424``configure`` script, make, and install for the SpatiaLite library::
 425
 426    $ cd libspatialite-amalgamation-2.3.1
 427    $ ./configure # May need to modified, see notes below.
 428    $ make
 429    $ sudo make install
 430    $ cd ..
 431
 432Finally, do the same for the SpatiaLite tools::
 433
 434    $ cd spatialite-tools-2.3.1
 435    $ ./configure # May need to modified, see notes below.
 436    $ make
 437    $ sudo make install
 438    $ cd ..
 439
 440.. note::
 441
 442    If you've installed GEOS and PROJ.4 from binary packages, you will have to specify
 443    their paths when running the ``configure`` scripts for *both* the library and the
 444    tools (the configure scripts look, by default, in ``/usr/local``).  For example,
 445    on Debian/Ubuntu distributions that have GEOS and PROJ.4 packages, the command would be::
 446
 447       $ ./configure --with-proj-include=/usr/include --with-proj-lib=/usr/lib --with-geos-include=/usr/include --with-geos-lib=/usr/lib
 448
 449.. note::
 450
 451    For Mac OS X users building from source, the SpatiaLite library *and* tools
 452    need to have their ``target`` configured::
 453
 454        $ ./configure --target=macosx
 455
 456__ http://www.gaia-gis.it/spatialite/sources.html
 457
 458.. _pysqlite2:
 459
 460pysqlite2
 461^^^^^^^^^
 462
 463Because SpatiaLite must be loaded as an external extension, it requires the
 464``enable_load_extension`` method, which is only available in versions 2.5+.
 465Thus, download pysqlite2 2.6, and untar::
 466
 467    $ wget http://pysqlite.googlecode.com/files/pysqlite-2.6.0.tar.gz
 468    $ tar xzf pysqlite-2.6.0.tar.gz
 469    $ cd pysqlite-2.6.0
 470
 471Next, use a text editor (e.g., ``emacs`` or ``vi``) to edit the ``setup.cfg`` file
 472to look like the following::
 473
 474    [build_ext]
 475    #define=
 476    include_dirs=/usr/local/include
 477    library_dirs=/usr/local/lib
 478    libraries=sqlite3
 479    #define=SQLITE_OMIT_LOAD_EXTENSION
 480
 481.. note::
 482
 483    The important thing here is to make sure you comment out the
 484    ``define=SQLITE_OMIT_LOAD_EXTENSION`` flag and that the ``include_dirs``
 485    and ``library_dirs`` settings are uncommented and set to the appropriate
 486    path if the SQLite header files and libraries are not in ``/usr/include``
 487    and ``/usr/lib``, respectively.
 488
 489After modifying ``setup.cfg`` appropriately, then run the ``setup.py`` script
 490to build and install::
 491
 492    $ sudo python setup.py install
 493
 494Post-Installation
 495=================
 496
 497.. _spatialdb_template:
 498
 499Creating a Spatial Database Template for PostGIS
 500------------------------------------------------
 501
 502Creating a spatial database with PostGIS is different than normal because
 503additional SQL must be loaded to enable spatial functionality.  Because of
 504the steps in this process, it's better to create a database template that
 505can be reused later.
 506
 507First, you need to be able to execute the commands as a privileged database
 508user.  For example, you can use the following to become the ``postgres`` user::
 509
 510    $ sudo su - postgres
 511
 512.. note::
 513
 514   The location *and* name of the PostGIS SQL files (e.g., from
 515   ``POSTGIS_SQL_PATH`` below) depends on the version of PostGIS.
 516   PostGIS versions 1.3 and below use ``<pg_sharedir>/contrib/lwpostgis.sql``;
 517   whereas version 1.4 uses ``<sharedir>/contrib/postgis.sql`` and
 518   version 1.5 uses ``<sharedir>/contrib/postgis-1.5/postgis.sql``.
 519
 520   To complicate matters, :ref:`ubuntudebian` distributions have their
 521   own separate directory naming system that changes each release.
 522
 523   The example below assumes PostGIS 1.5, thus you may need to modify
 524   ``POSTGIS_SQL_PATH`` and the name of the SQL file for the specific
 525   version of PostGIS you are using.
 526
 527Once you're a database super user, then you may execute the following commands
 528to create a PostGIS spatial database template::
 529
 530    $ POSTGIS_SQL_PATH=`pg_config --sharedir`/contrib/postgis-1.5
 531    # Creating the template spatial database.
 532    $ createdb -E UTF8 template_postgis
 533    $ createlang -d template_postgis plpgsql # Adding PLPGSQL language support.
 534    # Allows non-superusers the ability to create from this template
 535    $ psql -d postgres -c "UPDATE pg_database SET datistemplate='true' WHERE datname='template_postgis';"
 536    # Loading the PostGIS SQL routines
 537    $ psql -d template_postgis -f $POSTGIS_SQL_PATH/postgis.sql
 538    $ psql -d template_postgis -f $POSTGIS_SQL_PATH/spatial_ref_sys.sql
 539    # Enabling users to alter spatial tables.
 540    $ psql -d template_postgis -c "GRANT ALL ON geometry_columns TO PUBLIC;"
 541    $ psql -d template_postgis -c "GRANT ALL ON geography_columns TO PUBLIC;"
 542    $ psql -d template_postgis -c "GRANT ALL ON spatial_ref_sys TO PUBLIC;"
 543
 544These commands may be placed in a shell script for later use; for convenience
 545the following scripts are available:
 546
 547===============  =============================================
 548PostGIS Version  Bash Shell Script
 549===============  =============================================
 5501.3              :download:`create_template_postgis-1.3.sh`
 5511.4              :download:`create_template_postgis-1.4.sh`
 5521.5              :download:`create_template_postgis-1.5.sh`
 553Debian/Ubuntu    :download:`create_template_postgis-debian.sh`
 554===============  =============================================
 555
 556Afterwards, you may create a spatial database by simply specifying
 557``template_postgis`` as the template to use (via the ``-T`` option)::
 558
 559    $ createdb -T template_postgis <db name>
 560
 561.. note::
 562
 563    While the ``createdb`` command does not require database super-user privileges,
 564    it must be executed by a database user that has permissions to create databases.
 565    You can create such a user with the following command::
 566
 567        $ createuser --createdb <user>
 568
 569.. _create_spatialite_db:
 570
 571Creating a Spatial Database for SpatiaLite
 572-------------------------------------------
 573
 574After the SpatiaLite library and tools have been installed, it is now possible
 575to create spatial database for use with GeoDjango.  In order to do this, download
 576the spatial database initialization SQL from the `SpatiaLite Resources`__ page::
 577
 578   $ wget http://www.gaia-gis.it/spatialite/init_spatialite-2.3.sql.gz
 579   $ gunzip init_spatialite-2.3.sql.gz
 580
 581Now, the ``spatialite`` command can be used to initialize a spatial database::
 582
 583   $ spatialite geodjango.db < init_spatialite-2.3.sql
 584
 585.. note::
 586
 587    The parameter ``geodjango.db`` is the *filename* of the SQLite database
 588    you want to use.  Use the same in the :setting:`DATABASE_NAME`
 589    inside your ``settings.py``.
 590
 591
 592__ http://www.gaia-gis.it/spatialite/resources.html
 593
 594
 595Add ``django.contrib.gis`` to :setting:`INSTALLED_APPS`
 596-------------------------------------------------------
 597
 598Like other Django contrib applications, you will *only* need to add
 599:mod:`django.contrib.gis` to :setting:`INSTALLED_APPS` in your settings.
 600This is the so that ``gis`` templates can be located -- if not done, then
 601features such as the geographic admin or KML sitemaps will not function properly.
 602
 603.. _addgoogleprojection:
 604
 605Add Google Projection to ``spatial_ref_sys`` table
 606--------------------------------------------------
 607
 608.. versionchanged:: 1.2
 609
 610.. note::
 611
 612    If running PostGIS 1.4 and above, the entry is already included in the
 613    default ``spatial_ref_sys`` table.  You can skip this step.
 614
 615In order to conduct database transformations to the so-called "Google"
 616projection (a spherical mercator projection used by Google Maps),
 617an entry must be added to your spatial database's ``spatial_ref_sys`` table.
 618Invoke the Django shell from your project and execute the
 619``add_srs_entry`` function::
 620
 621    $ python manage shell
 622    >>> from django.contrib.gis.utils import add_srs_entry
 623    >>> add_srs_entry(900913)
 624
 625.. note::
 626
 627    In Django 1.1 the name of this function is ``add_postgis_srs``.
 628
 629This adds an entry for the 900913 SRID to the ``spatial_ref_sys`` (or equivalent)
 630table, making it possible for the spatial database to transform coordinates in
 631this projection.  You only need to execute this command *once* per spatial database.
 632
 633Troubleshooting
 634===============
 635
 636If you can't find the solution to your problem here then participate in the
 637community!  You can:
 638
 639* Join the ``#geodjango`` IRC channel on FreeNode (may be accessed on the
 640  Web via `Mibbit`__).  Please be patient and polite -- while you may not
 641  get an immediate response, someone will attempt to answer your question
 642  as soon as they see it.
 643* Ask your question on the `GeoDjango`__ mailing list.
 644* File a ticket on the `Django trac`__ if you think there's a bug.  Make
 645  sure to provide a complete description of the problem, versions used,
 646  and specify the component as "GIS".
 647
 648__ http://www.mibbit.com/?server=irc.freenode.net&channel=%23geodjango
 649__ http://groups.google.com/group/geodjango
 650__ http://code.djangoproject.com/simpleticket
 651
 652.. _libsettings:
 653
 654Library Environment Settings
 655----------------------------
 656
 657By far, the most common problem when installing GeoDjango is that the
 658external shared libraries (e.g., for GEOS and GDAL) cannot be located. [#]_
 659Typically, the cause of this problem is that the operating system isn't aware
 660of the directory where the libraries built from source were installed.
 661
 662In general, the library path may be set on a per-user basis by setting
 663an environment variable, or by configuring the library path for the entire
 664system.
 665
 666``LD_LIBRARY_PATH`` environment variable
 667^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 668
 669A user may set this environment variable to customize the library paths
 670they want to use.  The typical library directory for software
 671built from source is ``/usr/local/lib``.  Thus, ``/usr/local/lib`` needs
 672to be included in the ``LD_LIBRARY_PATH`` variable.  For example, the user
 673could place the following in their bash profile::
 674
 675    export LD_LIBRARY_PATH=/usr/local/lib
 676
 677Setting System Library Path
 678^^^^^^^^^^^^^^^^^^^^^^^^^^^
 679
 680On GNU/Linux systems, there is typically a file in ``/etc/ld.so.conf``, which may include
 681additional paths from files in another directory, such as ``/etc/ld.so.conf.d``.
 682As the root user, add the custom library path (like ``/usr/local/lib``) on a
 683new line in ``ld.so.conf``.  This is *one* example of how to do so::
 684
 685    $ sudo echo /usr/local/lib >> /etc/ld.so.conf
 686    $ sudo ldconfig
 687
 688For OpenSolaris users, the system library path may be modified using the
 689``crle`` utility.  Run ``crle`` with no options to see the current configuration
 690and use ``crle -l`` to set with the new library path.  Be *very* careful when
 691modifying the system library path::
 692
 693    # crle -l $OLD_PATH:/usr/local/lib
 694
 695.. _binutils:
 696
 697Install ``binutils``
 698^^^^^^^^^^^^^^^^^^^^
 699
 700GeoDjango uses the ``find_library`` function (from the ``ctypes.util`` Python
 701module) to discover libraries.  The ``find_library`` routine uses a program
 702called ``objdump`` (part of the ``binutils`` package) to verify a shared
 703library on GNU/Linux systems.  Thus, if ``binutils`` is not installed on your
 704Linux system then Python's ctypes may not be able to find your library even if
 705your library path is set correctly and geospatial libraries were built perfectly.
 706
 707The ``binutils`` package may be installed on Debian and Ubuntu systems using the
 708following command::
 709
 710    $ sudo apt-get install binutils
 711
 712Similarly, on Red Hat and CentOS systems::
 713
 714    $ sudo yum install binutils
 715
 716Platform Specific Instructions
 717==============================
 718
 719.. _macosx:
 720
 721Mac OS X
 722--------
 723
 724Because of the variety of packaging systems available for OS X, users have
 725several different options for installing GeoDjango.  These options are:
 726
 727* :ref:`kyngchaos`
 728* :ref:`fink`
 729* :ref:`macports`
 730* :ref:`build_from_source`
 731
 732.. note::
 733
 734    Currently, the easiest and recommended approach for installing GeoDjango
 735    on OS X is to use the KyngChaos packages.
 736
 737This section also includes instructions for installing an upgraded version
 738of :ref:`macosx_python` from packages provided by the Python Software
 739Foundation, however, this is not required.
 740
 741.. _macosx_python:
 742
 743Python
 744^^^^^^
 745
 746Although OS X comes with Python installed, users can use framework
 747installers (`2.5`__ and `2.6`__ are available) provided by
 748the Python Software Foundation.  An advantage to using the installer is
 749that OS X's Python will remain "pristine" for internal operating system
 750use.
 751
 752__ http://python.org/ftp/python/2.5.4/python-2.5.4-macosx.dmg
 753__ http://python.org/ftp/python/2.6.2/python-2.6.2-macosx2009-04-16.dmg
 754
 755.. note::
 756
 757    You will need to modify the ``PATH`` environment variable in your
 758    ``.profile`` file so that the new version of Python is used when
 759    ``python`` is entered at the command-line::
 760
 761        export PATH=/Library/Frameworks/Python.framework/Versions/Current/bin:$PATH
 762
 763.. _kyngchaos:
 764
 765KyngChaos Packages
 766^^^^^^^^^^^^^^^^^^
 767
 768William Kyngesburye provides a number of `geospatial library binary packages`__
 769that make it simple to get GeoDjango installed on OS X without compiling
 770them from source.  However, the `Apple Developer Tools`_ are still necessary
 771for compiling the Python database adapters :ref:`psycopg2_kyngchaos` (for PostGIS)
 772and :ref:`pysqlite2_kyngchaos` (for SpatiaLite).
 773
 774.. note::
 775
 776    SpatiaLite users should consult the :ref:`spatialite_kyngchaos` section
 777    after installing the packages for additional instructions.
 778
 779Download the framework packages for:
 780
 781* UnixImageIO
 782* PROJ
 783* GEOS
 784* SQLite3 (includes the SpatiaLite library)
 785* GDAL
 786
 787Install the packages in the order they are listed above, as the GDAL and SQLite
 788packages require the packages listed before them.  Afterwards, you can also
 789install the KyngChaos binary packages for `PostgreSQL and PostGIS`__.
 790
 791After installing the binary packages, you'll want to add the following to
 792your ``.profile`` to be able to run the package programs from the command-line::
 793
 794    export PATH=/Library/Frameworks/UnixImageIO.framework/Programs:$PATH
 795    export PATH=/Library/Frameworks/PROJ.framework/Programs:$PATH
 796    export PATH=/Library/Frameworks/GEOS.framework/Programs:$PATH
 797    export PATH=/Library/Frameworks/SQLite3.framework/Programs:$PATH
 798    export PATH=/Library/Frameworks/GDAL.framework/Programs:$PATH
 799    export PATH=/usr/local/pgsql/bin:$PATH
 800
 801__ http://www.kyngchaos.com/software/frameworks
 802__ http://www.kyngchaos.com/software/postgres
 803
 804.. note::
 805
 806    Use of these binaries requires Django 1.0.3 and above.  If you are
 807    using a previous version of Django (like 1.0.2), then you will have
 808    to add the following in your settings::
 809
 810        GEOS_LIBRARY_PATH='/Library/Frameworks/GEOS.framework/GEOS'
 811        GDAL_LIBRARY_PATH='/Library/Frameworks/GDAL.framework/GDAL'
 812
 813.. _psycopg2_kyngchaos:
 814
 815psycopg2
 816~~~~~~~~
 817
 818After you've installed the KyngChaos binaries and modified your ``PATH``, as
 819described above, ``psycopg2`` may be installed using the following command::
 820
 821    $ sudo python easy_install psycopg2
 822
 823.. note::
 824
 825   To use ``easy_install`` you'll need to install Python's `setuptools`_.
 826
 827.. _setuptools: http://pypi.python.org/pypi/setuptools
 828
 829.. _pysqlite2_kyngchaos:
 830
 831pysqlite2
 832~~~~~~~~~
 833
 834Follow the :ref:`pysqlite2` source install instructions, however,
 835when editing the ``setup.cfg`` use the following instead::
 836
 837    [build_ext]
 838    #define=
 839    include_dirs=/Library/Frameworks/SQLite3.framework/unix/include
 840    library_dirs=/Library/Frameworks/SQLite3.framework/unix/lib
 841    libraries=sqlite3
 842    #define=SQLITE_OMIT_LOAD_EXTENSION
 843
 844.. _spatialite_kyngchaos:
 845
 846SpatiaLite
 847~~~~~~~~~~
 848
 849When :ref:`create_spatialite_db`, the ``spatialite`` program is required.
 850However, instead of attempting to compile the SpatiaLite tools from source,
 851download the `SpatiaLite Binaries`__ for OS X, and install ``spatialite`` in a
 852location available in your ``PATH``.  For example::
 853
 854    $ curl -O http://www.gaia-gis.it/spatialite/spatialite-tools-osx-x86-2.3.1.tar.gz
 855    $ tar xzf spatialite-tools-osx-x86-2.3.1.tar.gz
 856    $ cd spatialite-tools-osx-x86-2.3.1/bin
 857    $ sudo cp spatialite /Library/Frameworks/SQLite3.framework/Programs
 858
 859Finally, for GeoDjango to be able to find the KyngChaos SpatiaLite library,
 860add the following to your ``settings.py``::
 861
 862    SPATIALITE_LIBRARY_PATH='/Library/Frameworks/SQLite3.framework/SQLite3'
 863
 864__ http://www.gaia-gis.it/spatialite/binaries.html
 865
 866.. _fink:
 867
 868Fink
 869^^^^
 870
 871`Kurt Schwehr`__ has been gracious enough to create GeoDjango packages for users
 872of the `Fink`__ package system.  The following packages are available, depending
 873on which version of Python you want to use:
 874
 875* ``django-gis-py26``
 876* ``django-gis-py25``
 877* ``django-gis-py24``
 878
 879__ http://schwehr.org/blog/
 880__ http://www.finkproject.org/
 881
 882.. _macports:
 883
 884MacPorts
 885^^^^^^^^
 886
 887`MacPorts`__ may be used to install GeoDjango prerequisites on Macintosh
 888computers running OS X.  Because MacPorts still builds the software from source,
 889the `Apple Developer Tools`_ are required.
 890
 891Summary::
 892
 893    $ sudo port install postgresql83-server
 894    $ sudo port install geos
 895    $ sudo port install proj
 896    $ sudo port install postgis
 897    $ sudo port install gdal
 898    $ sudo port install libgeoip
 899
 900.. note::
 901
 902    You will also have to modify the ``PATH`` in your ``.profile`` so
 903    that the MacPorts programs are accessible from the command-line::
 904
 905        export PATH=/opt/local/bin:/opt/local/lib/postgresql83/bin
 906
 907    In addition, add the ``DYLD_FALLBACK_LIBRARY_PATH`` setting so that
 908    the libraries can be found by Python::
 909
 910        export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:/opt/local/lib/postgresql83
 911
 912__ http://www.macports.org/
 913
 914.. _ubuntudebian:
 915
 916Ubuntu & Debian GNU/Linux
 917-------------------------
 918
 919.. note::
 920
 921    The PostGIS SQL files are not placed the PostgreSQL share directory in the
 922    Debian and Ubuntu packages, and are located instead special directory
 923    depending on the release.  Thus, when :ref:`spatialdb_template` use the
 924    :download:`create_template_postgis-debian.sh` script instead
 925
 926.. _ubuntu:
 927
 928Ubuntu
 929^^^^^^
 930
 931.. _ubuntu10:
 932
 93310.04 and 10.10
 934~~~~~~~~~~~~~~~
 935
 936In Ubuntu 10 PostgreSQL was upgraded to 8.4 and GDAL was upgraded to 1.6.
 937Ubuntu 10.04 uses PostGIS 1.4, while Ubuntu 10.10 uses PostGIS 1.5 (with
 938geography support).  The installation commands are::
 939
 940    $ sudo apt-get install binutils gdal-bin postgresql-8.4-postgis \
 941         postgresql-server-dev-8.4 python-psycopg2 python-setuptools
 942    $ sudo easy_install Django
 943
 944.. _ibex:
 945
 9468.10
 947~~~~
 948
 949Use the synaptic package manager to install the following packages::
 950
 951    $ sudo apt-get install binutils gdal-bin postgresql-8.3-postgis \
 952        postgresql-server-dev-8.3 python-psycopg2 python-setuptools
 953
 954Afterwards, you may install Django with Python's ``easy_install`` script (the
 955Ubuntu package ``python-django`` uses an older version missing several
 956important bug fixes for GeoDjango)::
 957
 958    $ sudo easy_install Django
 959
 960That's it!  For the curious, the required binary prerequisites packages are:
 961
 962* ``binutils``: for ctypes to find libraries
 963* ``postgresql-8.3``
 964* ``postgresql-server-dev-8.3``: for ``pg_config``
 965* ``postgresql-8.3-postgis``: for PostGIS 1.3.3
 966* ``libgeos-3.0.0``, and ``libgeos-c1``: for GEOS 3.0.0
 967* ``libgdal1-1.5.0``: for GDAL 1.5.0 library
 968* ``proj``: for PROJ 4.6.0 -- but no datum shifting files, see note below
 969* ``python-psycopg2``
 970* ``python-setuptools``: for ``easy_install``
 971
 972Optional packages to consider:
 973
 974* ``libgeoip1``: for :ref:`GeoIP <ref-geoip>` support
 975* ``gdal-bin``: for GDAL command line programs like ``ogr2ogr``
 976* ``python-gdal`` for GDAL's own Python bindings -- includes interfaces for raster manipulation
 977
 978.. note::
 979
 980    On this version of Ubuntu the ``proj`` package does not come with the
 981    datum shifting files installed, which will cause problems with the
 982    geographic admin because the ``null`` datum grid is not available for
 983    transforming geometries to the spherical mercator projection. A solution
 984    is to download the datum-shifting files, create the grid file, and
 985    install it yourself::
 986
 987        $ wget http://download.osgeo.org/proj/proj-datumgrid-1.4.tar.gz
 988        $ mkdir nad
 989        $ cd nad
 990        $ tar xzf ../proj-datumgrid-1.4.tar.gz
 991        $ nad2bin null < null.lla
 992        $ sudo cp null /usr/share/proj
 993
 994    Otherwise, the Ubuntu ``proj`` package is fine for general use as long as you
 995    do not plan on doing any database transformation of geometries to the
 996    Google projection (900913).
 997
 998.. _heron:
 999
10008.04 and lower
1001~~~~~~~~~~~~~~
1002
1003The 8.04 (and lower) versions of Ubuntu use GEOS v2.2.3 in their binary packages,
1004which is incompatible with GeoDjango.  Thus, do *not* use the binary packages
1005for GEOS or PostGIS and build some prerequisites from source, per the instructions
1006in this document; however, it is okay to use the PostgreSQL binary packages.
1007
1008For more details, please see the Debian instructions for :ref:`etch` below.
1009
1010.. _debian:
1011
1012Debian
1013------
1014
1015.. _etch:
1016
10174.0 (Etch)
1018^^^^^^^^^^
1019The situation here is the same as that of Ubuntu :ref:`heron` -- in other words,
1020some packages must be built from source to work properly with GeoDjango.
1021
1022Binary Packages
1023~~~~~~~~~~~~~~~
1024The following command will install acceptable binary packages, as well as
1025the development tools necessary to build the rest of the requirements::
1026
1027    $ sudo apt-get install binutils bzip2 gcc g++ flex make postgresql-8.1 postgresql-server-dev-8.1 python-ctypes python-psycopg2 python-setuptools
1028
1029Required package information:
1030
1031* ``binutils``: for ctypes to find libraries
1032* ``bzip2``: for decompressing the source packages
1033* ``gcc``, ``g++``, ``make``: GNU developer tools used to compile the libraries
1034* ``flex``: required to build PostGIS
1035* ``postgresql-8.1``
1036* ``postgresql-server-dev-8.1``: for ``pg_config``
1037* ``python-ctypes``: Python 2.4 needs to have ctypes installed separately
1038* ``python-psycopg2``
1039* ``python-setuptools``: for ``easy_install``
1040
1041Optional packages:
1042
1043* ``libgeoip``: for :ref:`GeoIP <ref-geoip>` support
1044
1045Source Packages
1046~~~~~~~~~~~~~~~
1047You will still have to install :ref:`geosbuild`, :ref:`proj4`,
1048:ref:`postgis`, and :ref:`gdalbuild` from source.  Please follow the
1049directions carefully.
1050
1051.. _lenny:
1052
10535.0 (Lenny)
1054^^^^^^^^^^^
1055
1056This version is comparable to Ubuntu :ref:`ibex`, so the command
1057is very similar::
1058
1059    $ 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
1060
1061This assumes that you are using PostgreSQL version 8.3. Else, replace ``8.3``
1062in the above command with the appropriate PostgreSQL version.
1063
1064.. note::
1065
1066   Please read the note in the Ubuntu :ref:`ibex` install documentation
1067   about the ``proj`` package -- it also applies here because the package does
1068   not include the datum shifting files.
1069
1070.. _post_install:
1071
1072Post-installation Notes
1073~~~~~~~~~~~~~~~~~~~~~~~
1074
1075If the PostgreSQL database cluster was not initiated after installing, then it
1076can be created (and started) with the following command::
1077
1078    $ sudo pg_createcluster --start 8.3 main
1079
1080Afterwards, the ``/etc/init.d/postgresql-8.3`` script should be used to manage
1081the starting and stopping of PostgreSQL.
1082
1083In addition, the SQL files for PostGIS are placed in a different location on
1084Debian 5.0 . Thus when :ref:`spatialdb_template` either:
1085
1086* Create a symbolic link to these files::
1087
1088    $ sudo ln -s /usr/share/postgresql-8.3-postgis/{lwpostgis,spatial_ref_sys}.sql /usr/share/postgresql/8.3
1089
1090  If not running PostgreSQL 8.3, then  replace ``8.3`` in the command above with the correct version.
1091
1092* Or use the :download:`create_template_postgis-debian.sh` to create the spatial database.
1093
1094.. _windows:
1095
1096Windows
1097-------
1098
1099Proceed through the following sections sequentially in order to install
1100GeoDjango on Windows.
1101
1102.. note::
1103
1104    These instructions assume that you are using 32-bit versions of
1105    all programs.  While 64-bit versions of Python and PostgreSQL 9.0
1106    are available, 64-bit versions of spatial libraries, like
1107    GEOS and GDAL, are not yet provided by the :ref:`OSGeo4W` installer.
1108
1109Python
1110^^^^^^
1111
1112First, download the latest `Python 2.7 installer`__ from the Python Web site.
1113Next, run the installer and keep the defaults -- for example, keep 
1114'Install for all users' checked and the installation path set as
1115``C:\Python27``.
1116
1117.. note::
1118
1119    You may already have a version of Python installed in ``C:\python`` as ESRI
1120    products sometimes install a copy there.  *You should still install a
1121    fresh version of Python 2.7.*
1122
1123__ http://python.org/download/
1124
1125PostgreSQL
1126^^^^^^^^^^
1127
1128First, download the latest `PostgreSQL 9.0 installer`__ from the
1129`EnterpriseDB`__ Web site.  After downloading, simply run the installer,
1130follow the on-screen directions, and keep the default options unless
1131you know the consequences of changing them.
1132
1133.. note::
1134
1135    The PostgreSQL installer creates both a new Windows user to be the
1136    'postgres service account' and a ``postgres`` database superuser
1137    You will be prompted once to set the password for both accounts --
1138    make sure to remember it!
1139
1140When the installer completes, it will ask to launch the Application Stack
1141Builder (ASB) on exit -- keep this checked, as it is necessary to
1142install :ref:`postgisasb`.
1143
1144.. note::
1145
1146    If installed successfully, the PostgreSQL server will run in the
1147    background each time the system as started as a Windows service.
1148    A :menuselection:`PostgreSQL 9.0` start menu group will created
1149    and contains shortcuts for the ASB as well as the 'SQL Shell',
1150    which will launch a ``psql`` command window.
1151
1152__ http://www.enterprisedb.com/products-services-training/pgdownload
1153__ http://www.enterprisedb.com
1154
1155.. _postgisasb:
1156
1157PostGIS
1158^^^^^^^
1159
1160From within the Application Stack Builder (to run outside of the installer,
1161:menuselection:`Start --> Programs --> PostgreSQL 9.0`), select
1162:menuselection:`PostgreSQL Database Server 9.0 on port 5432` from the drop down
1163menu.  Next, expand the :menuselection:`Categories --> Spatial Extensions` menu
1164tree and select :menuselection:`PostGIS 1.5 for PostgreSQL 9.0`.
1165
1166After clicking next, you will be prompted to select your mirror, PostGIS
1167will be downloaded, and the PostGIS installer will begin.  Select only the
1168default options during install (e.g., do not uncheck the option to create a 
1169default PostGIS database).
1170
1171.. note::
1172
1173    You will be prompted to enter your ``postgres`` database superuser
1174    password in the 'Database Connection Information' dialog.
1175
1176psycopg2
1177^^^^^^^^
1178
1179The ``psycopg2`` Python module provides the interface between Python and the
1180PostgreSQL database.  Download the latest `Windows installer`__ for your version
1181of Python and PostgreSQL and run using the default settings. [#]_
1182
1183__ http://www.stickpeople.com/projects/python/win-psycopg/
1184
1185.. _osgeo4w:
1186
1187OSGeo4W
1188^^^^^^^
1189
1190The `OSGeo4W installer`_ makes it simple to install the PROJ.4, GDAL, and GEOS
1191libraries required by GeoDjango.  First, download the `OSGeo4W installer`_,
1192and run it.  Select :menuselection:`Express Web-GIS Install` and click next.
1193In the 'Select Packages' list, ensure that GDAL is selected; MapServer and
1194Apache are also enabled by default, but are not required by GeoDjango and
1195may be unchecked safely.  After clicking next, the packages will be
1196automatically downloaded and installed, after which you may exit the
1197installer.
1198
1199.. _OSGeo4W installer: http://trac.osgeo.org/osgeo4w/
1200
1201Modify Windows Environment
1202^^^^^^^^^^^^^^^^^^^^^^^^^^
1203
1204In order to use GeoDjango, you will need to add your Python and OSGeo4W
1205directories to your Windows system ``Path``, as well as create ``GDAL_DATA``
1206and ``PROJ_LIB`` environment variables.  The following set of commands,
1207executable with ``cmd.exe``, will set this up::
1208
1209     set OSGEO4W_ROOT=C:\OSGeo4W
1210     set PYTHON_ROOT=C:\Python27
1211     set GDAL_DATA=%OSGEO4W_ROOT%\share\gdal
1212     set PROJ_LIB=%OSGEO4W_ROOT%\share\proj
1213     set PATH=%PATH%;%PYTHON_ROOT%;%OSGEO4W_ROOT%\bin
1214     reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v Path /t REG_EXPAND_SZ /f /d "%PATH%"
1215     reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v GDAL_DATA /t REG_EXPAND_SZ /f /d "%GDAL_DATA%"
1216     reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v PROJ_LIB /t REG_EXPAND_SZ /f /d "%PROJ_LIB%"
1217
1218For your convenience, these commands are available in the execuatble batch
1219script, :download:`geodjango_setup.bat`.  
1220
1221.. note::
1222
1223    Administrator privileges are required to execute these commands.
1224    To do this, right-click on :download:`geodjango_setup.bat` and select
1225    :menuselection:`Run as administrator`. You need to log out and log back in again
1226    for the settings to take effect.
1227
1228.. note::
1229
1230    If you customized the Python or OSGeo4W installation directories,
1231    then you will need to modify the ``OSGEO4W_ROOT`` and/or ``PYTHON_ROOT``
1232    variables accordingly.
1233
1234Install Django and Setup Database
1235^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1236
1237Finally, :ref:`install Django <installing-official-release>` on your system.
1238You do not need to create a spatial database template, as one named
1239``template_postgis`` is created for you when installing PostGIS.
1240
1241To administer the database, you can either use the pgAdmin III program
1242(:menuselection:`Start --> PostgreSQL 9.0 --> pgAdmin III`) or the
1243SQL Shell (:menuselection:`Start --> PostgreSQL 9.0 --> SQL Shell`).
1244For example, to create a ``geodjango`` spatial database and user, the following
1245may be executed from the SQL Shell as the ``postgres`` user::
1246
1247    postgres# CREATE USER geodjango PASSWORD 'my_passwd';
1248    postgres# CREATE DATABASE geodjango OWNER geodjango TEMPLATE template_postgis ENCODING 'utf8';
1249
1250.. rubric:: Footnotes
1251.. [#] The datum shifting files are needed for converting data to and from certain projections.
1252       For example, the PROJ.4 string for the `Google projection (900913) <http://spatialreference.org/ref/epsg/900913/proj4>`_
1253       requires the ``null`` grid file only included in the extra datum shifting files.
1254       It is easier to install the shifting files now, then to have debug a problem caused by their absence later.
1255.. [#] Specifically, GeoDjango provides support for the `OGR <http://gdal.org/ogr>`_ library, a component of GDAL.
1256.. [#] See `GDAL ticket #2382 <http://trac.osgeo.org/gdal/ticket/2382>`_.
1257.. [#] GeoDjango uses the `find_library <http://docs.python.org/library/ctypes.html#finding-shared-libraries>`_
1258       routine from ``ctypes.util`` to locate shared libraries.
1259.. [#] The ``psycopg2`` Windows installers are packaged and maintained by
1260       `Jason Erickson <http://www.stickpeople.com/projects/python/win-psycopg/>`_.