Debian Codegraph @

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

raw
1 ======================
2 GeoDjango Installation
3 ======================
4
5 Overview
6 ========
7 In general, GeoDjango installation requires:
8
9 #. :ref:`Python and Django <django>`
10 #. :ref:`spatial_database`
11 #. :doc:`geolibs`
12
13 Details for each of the requirements and installation instructions
14 are provided in the sections below. In addition, platform-specific
15 instructions are available for:
16
17 * :ref:`macos`
18 * :ref:`windows`
19
20 .. admonition:: Use the Source
21
22 Because GeoDjango takes advantage of the latest in the open source geospatial
23 software technology, recent versions of the libraries are necessary.
24 If binary packages aren't available for your platform, installation from
25 source may be required. When compiling the libraries from source, please
26 follow the directions closely, especially if you're a beginner.
27
28 Requirements
29 ============
30
31 .. _django:
32
33 Python and Django
34 -----------------
35
36 Because GeoDjango is included with Django, please refer to Django's
37 :ref:`installation instructions <installing-official-release>` for details on
38 how to install.
39
40 .. _spatial_database:
41
42 Spatial database
43 ----------------
44 PostgreSQL (with PostGIS), MySQL, Oracle, and SQLite (with SpatiaLite) are the
45 spatial databases currently supported.
46
47 .. note::
48
49 PostGIS is recommended, because it is the most mature and feature-rich
50 open source spatial database.
51
52 The geospatial libraries required for a GeoDjango installation depends
53 on the spatial database used. The following lists the library requirements,
54 supported versions, and any notes for each of the supported database backends:
55
56 ================== ============================== ================== =========================================
57 Database Library Requirements Supported Versions Notes
58 ================== ============================== ================== =========================================
59 PostgreSQL GEOS, GDAL, PROJ, PostGIS 14+ Requires PostGIS.
60 MySQL GEOS, GDAL 8.0.11+ :ref:`Limited functionality <mysql-spatial-limitations>`.
61 Oracle GEOS, GDAL 19+ XE not supported.
62 SQLite GEOS, GDAL, PROJ, SpatiaLite 3.31.0+ Requires SpatiaLite 4.3+
63 ================== ============================== ================== =========================================
64
65 See also `this comparison matrix`__ on the OSGeo Wiki for
66 PostgreSQL/PostGIS/GEOS/GDAL possible combinations.
67
68 __ https://trac.osgeo.org/postgis/wiki/UsersWikiPostgreSQLPostGIS
69
70 Installation
71 ============
72
73 Geospatial libraries
74 --------------------
75
76 .. toctree::
77 :maxdepth: 1
78
79 geolibs
80
81 Database installation
82 ---------------------
83
84 .. toctree::
85 :maxdepth: 1
86
87 postgis
88 spatialite
89
90 :setting:`DATABASES` configuration
91 ----------------------------------
92
93 Set the :setting:`ENGINE <DATABASE-ENGINE>` setting to one of the :ref:`spatial
94 backends <spatial-backends>`.
95
96 Add ``django.contrib.gis`` to :setting:`INSTALLED_APPS`
97 -------------------------------------------------------
98
99 Like other Django contrib applications, you will *only* need to add
100 :mod:`django.contrib.gis` to :setting:`INSTALLED_APPS` in your settings.
101 This is so that the ``gis`` templates can be located -- if not done, then
102 features such as the geographic admin or KML sitemaps will not function properly.
103
104 Troubleshooting
105 ===============
106
107 If you can't find the solution to your problem here then participate in the
108 community! You can:
109
110 * Ask your question on the `GeoDjango`__ forum.
111 * File a ticket on the `Django trac`__ if you think there's a bug. Make
112 sure to provide a complete description of the problem, versions used,
113 and specify the component as "GIS".
114
115 __ https://forum.djangoproject.com/c/internals/geodjango/13
116 __ https://code.djangoproject.com/newticket
117
118 .. _libsettings:
119
120 Library environment settings
121 ----------------------------
122
123 By far, the most common problem when installing GeoDjango is that the
124 external shared libraries (e.g., for GEOS and GDAL) cannot be located. [#]_
125 Typically, the cause of this problem is that the operating system isn't aware
126 of the directory where the libraries built from source were installed.
127
128 In general, the library path may be set on a per-user basis by setting
129 an environment variable, or by configuring the library path for the entire
130 system.
131
132 ``LD_LIBRARY_PATH`` environment variable
133 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
134
135 A user may set this environment variable to customize the library paths
136 they want to use. The typical library directory for software
137 built from source is ``/usr/local/lib``. Thus, ``/usr/local/lib`` needs
138 to be included in the ``LD_LIBRARY_PATH`` variable. For example, the user
139 could place the following in their bash profile:
140
141 .. code-block:: shell
142
143 export LD_LIBRARY_PATH=/usr/local/lib
144
145 Setting system library path
146 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
147
148 On GNU/Linux systems, there is typically a file in ``/etc/ld.so.conf``, which may include
149 additional paths from files in another directory, such as ``/etc/ld.so.conf.d``.
150 As the root user, add the custom library path (like ``/usr/local/lib``) on a
151 new line in ``ld.so.conf``. This is *one* example of how to do so:
152
153 .. code-block:: shell
154
155 $ sudo echo /usr/local/lib >> /etc/ld.so.conf
156 $ sudo ldconfig
157
158 For OpenSolaris users, the system library path may be modified using the
159 ``crle`` utility. Run ``crle`` with no options to see the current configuration
160 and use ``crle -l`` to set with the new library path. Be *very* careful when
161 modifying the system library path:
162
163 .. code-block:: shell
164
165 # crle -l $OLD_PATH:/usr/local/lib
166
167 .. _binutils:
168
169 Install ``binutils``
170 ~~~~~~~~~~~~~~~~~~~~
171
172 GeoDjango uses the ``find_library`` function (from the ``ctypes.util`` Python
173 module) to discover libraries. The ``find_library`` routine uses a program
174 called ``objdump`` (part of the ``binutils`` package) to verify a shared
175 library on GNU/Linux systems. Thus, if ``binutils`` is not installed on your
176 Linux system then Python's ctypes may not be able to find your library even if
177 your library path is set correctly and geospatial libraries were built perfectly.
178
179 The ``binutils`` package may be installed on Debian and Ubuntu systems using the
180 following command:
181
182 .. code-block:: shell
183
184 $ sudo apt-get install binutils
185
186 Similarly, on Red Hat and CentOS systems:
187
188 .. code-block:: shell
189
190 $ sudo yum install binutils
191
192 Platform-specific instructions
193 ==============================
194
195 .. _macos:
196
197 macOS
198 -----
199
200 Because of the variety of packaging systems available for macOS, users have
201 several different options for installing GeoDjango. These options are:
202
203 * :ref:`postgresapp` (easiest and recommended)
204 * :ref:`homebrew`
205 * :ref:`fink`
206 * :ref:`macports`
207 * :ref:`build_from_source`
208
209 This section also includes instructions for installing an upgraded version
210 of :ref:`macos_python` from packages provided by the Python Software
211 Foundation, however, this is not required.
212
213 .. _macos_python:
214
215 Python
216 ~~~~~~
217
218 Although macOS comes with Python installed, users can use `framework
219 installers`__ provided by the Python Software Foundation. An advantage to
220 using the installer is that macOS's Python will remain "pristine" for internal
221 operating system use.
222
223 __ https://www.python.org/ftp/python/
224
225 .. note::
226
227 You will need to modify the ``PATH`` environment variable in your
228 ``.profile`` file so that the new version of Python is used when
229 ``python`` is entered at the command-line:
230
231 .. code-block:: shell
232
233 export PATH=/Library/Frameworks/Python.framework/Versions/Current/bin:$PATH
234
235 .. _postgresapp:
236
237 Postgres.app
238 ~~~~~~~~~~~~
239
240 `Postgres.app <https://postgresapp.com/>`_ is a standalone PostgreSQL server
241 that includes the PostGIS extension. You will also need to install ``gdal`` and
242 ``libgeoip`` with :ref:`homebrew`.
243
244 After installing Postgres.app, add the following to your ``.bash_profile`` so
245 you can run the package's programs from the command-line. Replace ``X.Y`` with
246 the version of PostgreSQL in the Postgres.app you installed:
247
248 .. code-block:: bash
249
250 export PATH=$PATH:/Applications/Postgres.app/Contents/Versions/X.Y/bin
251
252 You can check if the path is set up correctly by typing ``which psql`` at a
253 terminal prompt.
254
255 .. _homebrew:
256
257 Homebrew
258 ~~~~~~~~
259
260 `Homebrew`__ provides "recipes" for building binaries and packages from source.
261 It provides recipes for the GeoDjango prerequisites on Macintosh computers
262 running macOS. Because Homebrew still builds the software from source, `Xcode`_
263 is required.
264
265 Summary:
266
267 .. code-block:: shell
268
269 $ brew install postgresql
270 $ brew install postgis
271 $ brew install gdal
272 $ brew install libgeoip
273
274 __ https://brew.sh/
275 .. _Xcode: https://developer.apple.com/xcode/
276
277 .. _fink:
278
279 Fink
280 ^^^^
281
282 `Kurt Schwehr`__ has been gracious enough to create GeoDjango packages for users
283 of the `Fink`__ package system. `Different packages are available`__ (starting
284 with ``django-gis``), depending on which version of Python you want to use.
285
286 __ https://schwehr.blogspot.com/
287 __ https://www.finkproject.org/
288 __ https://pdb.finkproject.org/pdb/browse.php?summary=django-gis
289
290 .. _macports:
291
292 MacPorts
293 ~~~~~~~~
294
295 `MacPorts`__ may be used to install GeoDjango prerequisites on computers
296 running macOS. Because MacPorts still builds the software from source,
297 `Xcode`_ is required.
298
299 Summary:
300
301 .. code-block:: shell
302
303 $ sudo port install postgresql14-server
304 $ sudo port install geos
305 $ sudo port install proj6
306 $ sudo port install postgis3
307 $ sudo port install gdal
308 $ sudo port install libgeoip
309
310 .. note::
311
312 You will also have to modify the ``PATH`` in your ``.profile`` so
313 that the MacPorts programs are accessible from the command-line:
314
315 .. code-block:: shell
316
317 export PATH=/opt/local/bin:/opt/local/lib/postgresql14/bin
318
319 In addition, add the ``DYLD_FALLBACK_LIBRARY_PATH`` setting so that
320 the libraries can be found by Python:
321
322 .. code-block:: shell
323
324 export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:/opt/local/lib/postgresql14
325
326 __ https://www.macports.org/
327
328 .. _windows:
329
330 Windows
331 -------
332
333 Proceed through the following sections sequentially in order to install
334 GeoDjango on Windows. In this tutorial we will install 64 bit versions of each
335 application.
336
337 Python
338 ~~~~~~
339
340 Install a 64 bit version of Python. See :doc:`Install Python </howto/windows>`
341 for further information.
342
343 PostgreSQL
344 ~~~~~~~~~~
345
346 Download the latest `PostgreSQL 15.x installer`__ from the
347 `EnterpriseDB`__ website. After downloading, run the installer, follow the
348 on-screen directions, and keep the default options unless you know the
349 consequences of changing them.
350
351 .. note::
352
353 The PostgreSQL installer creates a new ``postgres`` database superuser
354 You will be prompted once to set the password -- make sure to remember it!
355
356 When the installer completes, it will ask to "Launch Stack Builder at exit?" --
357 keep this checked, as it is necessary to install :ref:`postgisasb`.
358
359 .. note::
360
361 If installed successfully, the PostgreSQL server will run in the background
362 each time the system as started as a Windows service. A
363 :menuselection:`PostgreSQL 15` start menu group will created and contains
364 shortcuts for the Application Stack Builder (ASB) as well as the
365 'SQL Shell', which will launch a ``psql`` command window.
366
367 __ https://www.enterprisedb.com/downloads/postgres-postgresql-downloads
368 __ https://www.enterprisedb.com
369
370 .. _postgisasb:
371
372 PostGIS
373 ~~~~~~~
374
375 From within the Stack Builder (to run outside of the installer,
376 :menuselection:`Start --> PostgreSQL 15 --> Application Stack Builder`), select
377 :menuselection:`PostgreSQL 15 (x64) on port 5432` from the drop down
378 menu and click next. Expand the
379 :menuselection:`Categories --> Spatial Extensions` menu tree and select
380 :menuselection:`PostGIS X.Y for PostgreSQL 15`.
381
382 After clicking next, you will be prompted to confirm the selected package and
383 "Download directory". Click next again, this will download PostGIS and you will
384 be asked to click next to begin the PostGIS installer. Select the default
385 options during install. The install process includes four Yes/No dialog boxes,
386 the default option for all four is "No".
387
388 .. _osgeo4w:
389
390 OSGeo4W
391 ~~~~~~~
392
393 The `OSGeo4W installer`_ helps to install the PROJ, GDAL, and GEOS libraries
394 required by GeoDjango. First, download the `OSGeo4W installer`_, and
395 run it. Select :menuselection:`Express Web-GIS Install` and click next. In the
396 'Select Packages' list, ensure that GDAL is selected. If any other packages are
397 enabled by default, they are not required by GeoDjango and may be unchecked
398 safely. After clicking next and accepting the license agreements, the packages
399 will be automatically downloaded and installed, after which you may exit the
400 installer.
401
402 .. _OSGeo4W installer: https://trac.osgeo.org/osgeo4w/
403
404 Modify Windows environment
405 ~~~~~~~~~~~~~~~~~~~~~~~~~~
406
407 In order to use GeoDjango, you will need to add your OSGeo4W
408 directories to your Windows system ``Path``, as well as create ``GDAL_DATA``
409 and ``PROJ_LIB`` environment variables. The following set of commands,
410 executable with ``cmd.exe``, will set this up. Restart your device
411 once this is complete for new environment variables to be recognized:
412
413 .. code-block:: bat
414
415 set OSGEO4W_ROOT=C:\OSGeo4W
416 set GDAL_DATA=%OSGEO4W_ROOT%\apps\gdal\share\gdal
417 set PROJ_LIB=%OSGEO4W_ROOT%\share\proj
418 set PATH=%PATH%;%OSGEO4W_ROOT%\bin
419 reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v Path /t REG_EXPAND_SZ /f /d "%PATH%"
420 reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v GDAL_DATA /t REG_EXPAND_SZ /f /d "%GDAL_DATA%"
421 reg ADD "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment" /v PROJ_LIB /t REG_EXPAND_SZ /f /d "%PROJ_LIB%"
422
423 .. note::
424
425 Administrator privileges are required to execute these commands.
426 To do this, run command prompt as administrator and enter the commands
427 above. You need to log out and log back in again for the settings to take
428 effect.
429
430 .. note::
431
432 If you customized the OSGeo4W installation directories, then you will need
433 to modify the ``OSGEO4W_ROOT`` variables accordingly.
434
435 Install Django and set up database
436 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
437
438 :ref:`Install Django <installing-official-release>` on your system. It is
439 recommended that you create a :doc:`virtual environment
440 <python:tutorial/venv>` for each project you create.
441
442 psycopg
443 ~~~~~~~
444
445 The ``psycopg`` Python module provides the interface between Python and the
446 PostgreSQL database. ``psycopg`` can be installed via pip within your Python
447 virtual environment:
448
449 .. code-block:: doscon
450
451 ...\> py -m pip install psycopg
452
453 .. rubric:: Footnotes
454 .. [#] GeoDjango uses the :func:`~ctypes.util.find_library` routine from
455 ``ctypes.util`` to locate shared libraries.