Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 515 lines (385 sloc) 23.05 kB
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
1 ==========================
2 Chapter 2: Getting Started
3 ==========================
4
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
5 Installing Django is a multi-step process, due to the multiple moving parts in
6 modern Web development environments. In this chapter, we'll walk you through
7 how to install the framework and its few dependencies.
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
8
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
9 Because Django is "just" Python code, it runs anywhere Python does -- including
10 on some cell phones! But this chapter just covers the common scenarios for
11 Django installations. We'll assume you're installing it either on a
12 desktop/laptop machine or a server.
13
14 Later, in Chapter 12, we'll cover how to deploy Django to a production site.
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
15
16 Installing Python
17 =================
18
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
19 Django itself is written purely in Python, so the first step in installing the
20 framework is to make sure you have Python installed.
21
22 Python Versions
23 ---------------
24
039ceb7 @mpdaugherty Remove whitespace at end of lines, wrap lines at 80 characters.
mpdaugherty authored
25 The core Django framework (version 1.4+) works with any Python version from 2.5
26 to 2.7, inclusive. Django's optional GIS (Geographic Information Systems)
27 support requires Python 2.5 to 2.7.
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
28
29 If you're not sure which version of Python to install and you have complete
8a2a33d @lgp171188 Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
30 freedom over the decision, pick the latest one in the 2.x series: version 2.7.
31 Although Django works equally well with any version from 2.5 to 2.7, the later
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
32 versions of Python have performance improvements and additional language
33 features you might like to use in your applications. Plus, certain third-party
34 Django add-ons that you might want to use might require a version newer than
8a2a33d @lgp171188 Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
35 Python 2.5, so using a later version of Python keeps your options open.
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
36
37 .. admonition:: Django and Python 3.0
38
39 At the time of writing, Python 3.0 had been released, but Django didn't
40 yet support it. Python 3.0 introduced a substantial number of
41 backwards-incompatible changes to the language itself, and, as a result,
42 we expect most major Python libraries and frameworks, including Django,
43 will take a few years to catch up.
44
45 If you're new to Python and are wondering whether to learn Python 2.x or
46 Python 3.x, our advice is to stick with Python 2.x.
47
48 Installation
49 ------------
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
50
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
51 If you're on Linux or Mac OS X, you probably have Python already installed.
52 Type ``python`` at a command prompt (or in Applications/Utilities/Terminal, in
53 OS X). If you see something like this, then Python is installed::
039ceb7 @mpdaugherty Remove whitespace at end of lines, wrap lines at 80 characters.
mpdaugherty authored
54
55 Python 2.7.3rc2 (default, Apr 22 2012, 22:30:17)
8a2a33d @lgp171188 Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
56 [GCC 4.6.3] on linux2
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
57 Type "help", "copyright", "credits" or "license" for more information.
039ceb7 @mpdaugherty Remove whitespace at end of lines, wrap lines at 80 characters.
mpdaugherty authored
58 >>>
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
59
60 Otherwise, you'll need to download and install Python. It's fast and easy, and
61 detailed instructions are available at http://www.python.org/download/
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
62
63 Installing Django
64 =================
65
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
66 At any given time, two distinct versions of Django are available to you: the
8a2a33d @lgp171188 Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
67 latest official release and the bleeding-edge development version. The version you
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
68 decide to install depends on your priorities. Do you want a stable and tested
69 version of Django, or do you want a version containing the latest features,
70 perhaps so you can contribute to Django itself, at the expense of stability?
71
72 We'd recommend sticking with an official release, but it's important to know
8a2a33d @lgp171188 Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
73 that the development version exists, because you'll find it mentioned
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
74 in the documentation and by members of the community.
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
75
76 Installing an Official Release
77 ------------------------------
78
8a2a33d @lgp171188 Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
79 Official releases have a version number, such as 1.4.1 or 1.4, and the latest
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
80 one is always available at http://www.djangoproject.com/download/.
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
81
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
82 If you're on a Linux distribution that includes a package of Django, it's a
83 good idea to use the distributor's version. That way, you'll get security
84 updates along with the rest of your system packages.
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
85
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
86 If you don't have access to a prepackaged version, you can download and install
87 the framework manually. To do so, first download the tarball, which will be
8a2a33d @lgp171188 Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
88 named something like ``Django-1.4.1.tar.gz``. (It doesn't matter which
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
89 local directory you download this file into; the installation process will put
90 Django's files in the right place.) Then, unzip it and run ``setup.py install``,
91 as you do with most Python libraries.
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
92
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
93 Here's how that process looks on Unix systems:
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
94
8a2a33d @lgp171188 Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
95 #. ``tar xzvf Django-1.4.1.tar.gz``
fdc4800 @jacobian Fixed a bunch of reST markup errors.
jacobian authored
96 #. ``cd Django-*``
97 #. ``sudo python setup.py install``
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
98
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
99 On Windows, we recommend using 7-Zip (http://www.djangoproject.com/r/7zip/)
100 to unzip ``.tar.gz`` files. Once you've unzipped the file, start up a DOS
101 shell (the "Command Prompt") with administrator privileges and run the
102 following command from within the directory whose name starts with ``Django-``::
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
103
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
104 python setup.py install
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
105
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
106 In case you're curious: Django's files will be installed into your Python
107 installation's ``site-packages`` directory -- a directory where Python looks
108 for third-party libraries. Usually it's in a place like
109 ``/usr/lib/python2.4/site-packages``.
110
8a2a33d @lgp171188 Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
111 Installing the "Development" Version
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
112 ------------------------------
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
113
039ceb7 @mpdaugherty Remove whitespace at end of lines, wrap lines at 80 characters.
mpdaugherty authored
114 Django uses Git (http://git-scm.com) for its source control. The latest and greatest
8a2a33d @lgp171188 Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
115 Django development version available from Django's official Git repository
116 (https://github.com/django/django). You should consider installing this version
117 if you want to work on the bleeding edge, or if you want to contribute code
118 to Django itself.
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
119
8a2a33d @lgp171188 Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
120 Git is a free, open source distributed revision-control system, and the Django team
121 uses it to manage changes to the Django codebase. You can download and install Git from
122 http://git-scm.com/download but it is easier to install with your operating system's
039ceb7 @mpdaugherty Remove whitespace at end of lines, wrap lines at 80 characters.
mpdaugherty authored
123 package manager. You can use Git to grab the very latest Django source code
8a2a33d @lgp171188 Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
124 and, at any given time, you can update your local version of the Django code
125 to get the latest changes and improvements made by Django developers.
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
126
039ceb7 @mpdaugherty Remove whitespace at end of lines, wrap lines at 80 characters.
mpdaugherty authored
127 When using the development version, keep in mind there's no guarantee
128 things won't be broken at any given moment. With that said, though,
129 some members of the Django team run production sites on development version,
8a2a33d @lgp171188 Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
130 so they have an incentive to keep it stable.
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
131
132 To grab the latest Django trunk, follow these steps:
133
8a2a33d @lgp171188 Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
134 #. Make sure you have Git installed. You can get the
135 software free from http://git-scm.com/, and you can find
136 excellent documentation at http://git-scm.com/documentation.
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
137
8a2a33d @lgp171188 Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
138 #. Clone the repository using the command ``git clone https://github.com/django/django djmaster``
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
139
fdc4800 @jacobian Fixed a bunch of reST markup errors.
jacobian authored
140 #. Locate your Python installation's ``site-packages`` directory. Usually
141 it's in a place like ``/usr/lib/python2.4/site-packages``. If you have
142 no idea, type this command from a command prompt::
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
143
fdc4800 @jacobian Fixed a bunch of reST markup errors.
jacobian authored
144 python -c 'import sys, pprint; pprint.pprint(sys.path)'
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
145
fdc4800 @jacobian Fixed a bunch of reST markup errors.
jacobian authored
146 The resulting output should include your ``site-packages`` directory.
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
147
fdc4800 @jacobian Fixed a bunch of reST markup errors.
jacobian authored
148 # Within the ``site-packages`` directory, create a file called
8a2a33d @lgp171188 Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
149 ``djmaster.pth`` and edit it to contain the full path to your ``djmaster``
fdc4800 @jacobian Fixed a bunch of reST markup errors.
jacobian authored
150 directory to it. For example, the file could just contain this line::
151
8a2a33d @lgp171188 Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
152 /path/to/djmaster
fdc4800 @jacobian Fixed a bunch of reST markup errors.
jacobian authored
153
8a2a33d @lgp171188 Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
154 #. Place ``djmaster/django/bin`` on your system PATH. This directory
fdc4800 @jacobian Fixed a bunch of reST markup errors.
jacobian authored
155 includes management utilities such as ``django-admin.py``.
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
156
157 .. admonition:: Tip:
158
fdc4800 @jacobian Fixed a bunch of reST markup errors.
jacobian authored
159 If ``.pth`` files are new to you, you can learn more about them at
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
160 http://www.djangoproject.com/r/python/site-module/.
161
8a2a33d @lgp171188 Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
162 After downloading from Git and following the preceding steps, there's no
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
163 need to run ``python setup.py install``-- you've just done the work by hand!
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
164
165 Because the Django trunk changes often with bug fixes and feature additions,
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
166 you'll probably want to update it every once in a while. To update the code,
8a2a33d @lgp171188 Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
167 just run the command ``git pull origin master`` from within the ``djmaster`` directory. When
168 you run that command, Git will contact https://github.com/django/django,
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
169 determine whether any of Django's code has changed, and update your local
170 version of the code with any changes that have been made since you last
171 updated. It's quite slick.
172
8a2a33d @lgp171188 Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
173 Finally, if you use Django development version, you should know how to figure out
174 which version of trunk you're running. Knowing your version number is important
175 if you ever need to reach out to the community for help, or if you submit improvements to the
176 framework. In these cases, you should tell people the revision, also known
039ceb7 @mpdaugherty Remove whitespace at end of lines, wrap lines at 80 characters.
mpdaugherty authored
177 as a "changeset," that you're using. To find out your HEAD changeset,
8a2a33d @lgp171188 Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
178 type "git log -1" from within the ``django`` directory, and
179 look for the identifier after "commit". This number changes each time
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
180 Django is changed, whether through a bug fix, feature addition, documentation
181 improvement or anything else. Among some members of the Django community, it's
182 a badge of honor to be able to say, "I've been using Django since [insert very
183 low revision number here]."
184
185 Testing the Django installation
186 ===============================
187
188 For some post-installation positive feedback, take a moment to test whether the
189 installation worked. In a command shell, change into another directory (e.g.,
190 *not* the directory that contains the ``django`` directory) and start the
191 Python interactive interpreter by typing ``python``. If the installation was
192 successful, you should be able to import the module ``django``:
193
194 >>> import django
195 >>> django.VERSION
4b613bf @lgp171188 Updated chapter02.rst for Django 1.4.1
lgp171188 authored
196 (1, 4, 1, 'final', 0)
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
197
198 .. admonition:: Interactive Interpreter Examples
199
200 The Python interactive interpreter is a command-line program that lets you
201 write a Python program interactively. To start it, run the command
202 ``python`` at the command line.
203
204 Throughout this book, we feature example Python interactive interpreter
205 sessions. You can recognize these examples by the triple
206 greater-than signs (``>>>``), which designate the interpreter's prompt. If
207 you're copying examples from this book, don't copy those greater-than signs.
208
209 Multiline statements in the interactive interpreter are padded with three
210 dots (``...``). For example::
211
212 >>> print """This is a
213 ... string that spans
214 ... three lines."""
215 This is a
216 string that spans
217 three lines.
218 >>> def my_function(value):
219 ... print value
220 >>> my_function('hello')
221 hello
222
223 Those three dots at the start of the additional lines are inserted by the
224 Python shell -- they're not part of our input. We include them here to be
225 faithful to the actual output of the interpreter. If you copy our examples
226 to follow along, don't copy those dots.
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
227
228 Setting Up a Database
229 =====================
230
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
231 At this point, you could very well begin writing a Web application with Django,
232 because Django's only hard-and-fast prerequisite is a working Python
233 installation. However, odds are you'll be developing a *database-driven* Web
234 site, in which case you'll need to configure a database server.
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
235
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
236 If you just want to start playing with Django, skip ahead to the
237 "Starting a Project" section -- but keep in mind that all the examples in this
238 book assume you have a working database set up.
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
239
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
240 Django supports four database engines:
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
241
fdc4800 @jacobian Fixed a bunch of reST markup errors.
jacobian authored
242 * PostgreSQL (http://www.postgresql.org/)
243 * SQLite 3 (http://www.sqlite.org/)
244 * MySQL (http://www.mysql.com/)
245 * Oracle (http://www.oracle.com/)
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
246
247 For the most part, all the engines here work equally well with the core Django
248 framework. (A notable exception is Django's optional GIS support, which is much
249 more powerful with PostgreSQL than with other databases.) If you're not tied to
250 any legacy system and have the freedom to choose a database backend, we
251 recommend PostgreSQL, which achieves a fine balance between cost, features,
252 speed and stability.
253
254 Setting up the database is a two-step process:
255
fdc4800 @jacobian Fixed a bunch of reST markup errors.
jacobian authored
256 * First, you'll need to install and configure the database server itself.
257 This process is beyond the scope of this book, but each of the four
258 database backends has rich documentation on its Web site. (If you're on
259 a shared hosting provider, odds are that they've set this up for you
260 already.)
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
261
fdc4800 @jacobian Fixed a bunch of reST markup errors.
jacobian authored
262 * Second, you'll need to install the Python library for your particular
263 database backend. This is a third-party bit of code that allows Python to
264 interface with the database. We outline the specific, per-database
265 requirements in the following sections.
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
266
267 If you're just playing around with Django and don't want to install a database
268 server, consider using SQLite. SQLite is unique in the list of supported
269 databases in that it doesn't require either of the above steps, if you're using
270 Python 2.5 or higher. It merely reads and writes its data to a single file on
271 your filesystem, and Python versions 2.5 and higher include built-in support
272 for it.
273
274 On Windows, obtaining database driver binaries can be frustrating. If you're
275 eager to jump in, we recommend using Python 2.5 and its built-in support for
276 SQLite.
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
277
278 Using Django with PostgreSQL
279 ----------------------------
280
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
281 If you're using PostgreSQL, you'll need to install either the ``psycopg`` or
282 ``psycopg2`` package from http://www.djangoproject.com/r/python-pgsql/. We
283 recommend ``psycopg2``, as it's newer, more actively developed and can be
284 easier to install. Either way, take note of whether you're using version 1 or
285 2; you'll need this information later.
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
286
287 If you're using PostgreSQL on Windows, you can find precompiled binaries of
288 ``psycopg`` at http://www.djangoproject.com/r/python-pgsql/windows/.
289
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
290 If you're on Linux, check whether your distribution's package-management
291 system offers a package called "python-psycopg2", "psycopg2-python",
292 "python-postgresql" or something similar.
293
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
294 Using Django with SQLite 3
295 --------------------------
296
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
297 If you're using Python version 2.5 or higher, you're in luck: no
298 database-specific installation is required, because Python ships with SQLite
299 support. Skip ahead to the next section.
300
301 If you're working with Python 2.4 or older, you'll need SQLite 3 -- *not*
302 version 2 -- from http://www.djangoproject.com/r/sqlite/ and the ``pysqlite``
303 package from http://www.djangoproject.com/r/python-sqlite/. Make sure you have
304 ``pysqlite`` version 2.0.3 or higher.
305
306 On Windows, you can skip installing the former (the separate SQLite binaries),
307 because they're statically linked into the ``pysqlite`` binaries.
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
308
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
309 If you're on Linux, check whether your distribution's package-management system
310 offers a package called "python-sqlite3", "sqlite-python", "pysqlite" or
311 something similar.
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
312
313 Using Django with MySQL
314 -----------------------
315
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
316 Django requires MySQL 4.0 or above. The 3.x versions don't support nested
317 subqueries and some other fairly standard SQL statements.
318
319 You'll also need to install the ``MySQLdb`` package from
320 http://www.djangoproject.com/r/python-mysql/.
321
322 If you're on Linux, check whether your distribution's package-management system
323 offers a package called "python-mysql", "python-mysqldb", "mysql-python" or
324 something similar.
325
326 Using Django with Oracle
327 ------------------------
328
329 Django works with Oracle Database Server versions 9i and higher.
330
331 If you're using Oracle, you'll need to install the ``cx_Oracle`` library,
332 available at http://cx-oracle.sourceforge.net/. Use version 4.3.1 or higher,
333 but avoid version 5.0 due to a bug in that version of the driver.
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
334
335 Using Django Without a Database
336 -------------------------------
337
338 As mentioned earlier, Django doesn't actually require a database. If you just
339 want to use it to serve dynamic pages that don't hit a database, that's
340 perfectly fine.
341
342 With that said, bear in mind that some of the extra tools bundled with Django
343 *do* require a database, so if you choose not to use a database, you'll miss
344 out on those features. (We highlight these features throughout this book.)
345
346 Starting a Project
347 ==================
348
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
349 Once you've installed Python, Django and (optionally) your database
350 server/library, you can take the first step in developing a Django application
351 by creating a *project*.
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
352
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
353 A project is a collection of settings for an instance of Django, including
354 database configuration, Django-specific options and application-specific
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
355 settings.
356
357 If this is your first time using Django, you'll have to take care of some
358 initial setup. Create a new directory to start working in, perhaps something
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
359 like ``/home/username/djcode/``.
360
361 .. admonition:: Where Should This Directory Live?
362
363 If your background is in PHP, you're probably used to putting code under the
364 Web server's document root (in a place such as ``/var/www``). With Django,
365 you don't do that. It's not a good idea to put any of this Python code
366 within your Web server's document root, because in doing so you risk the
367 possibility that people will be able to view your raw source code over the
368 Web. That's not good.
369
370 Put your code in some directory **outside** of the document root.
371
372 Change into the directory you created, and run the command
373 ``django-admin.py startproject mysite``. This will create a ``mysite``
374 directory in your current directory.
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
375
376 .. note::
377
378 ``django-admin.py`` should be on your system path if you installed Django
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
379 via its ``setup.py`` utility.
380
381 If you're using trunk, you'll find ``django-admin.py`` in
382 ``djtrunk/django/bin``. Because you'll be using ``django-admin.py``
383 often, consider adding it to your system path. On Unix, you can do so by
384 symlinking from ``/usr/local/bin``, using a command such as ``sudo ln -s
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
385 /path/to/django/bin/django-admin.py /usr/local/bin/django-admin.py``. On
386 Windows, you'll need to update your ``PATH`` environment variable.
387
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
388 If you installed Django from a packaged version for your Linux
389 distribution, ``django-admin.py`` might be called ``django-admin`` instead.
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
390
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
391 If you see a "permission denied" message when running
392 ``django-admin.py startproject``, you'll need to change the file's permissions.
393 To do this, navigate to the directory where ``django-admin.py`` is installed
394 (e.g., ``cd /usr/local/bin``) and run the command ``chmod +x django-admin.py``.
395
396 The ``startproject`` command creates a directory containing four files::
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
397
398 mysite/
399 manage.py
4b613bf @lgp171188 Updated chapter02.rst for Django 1.4.1
lgp171188 authored
400 mysite/
401 __init__.py
402 settings.py
403 urls.py
404 wsgi.py
405
406 .. note:: Doesn't match what you see?
407
039ceb7 @mpdaugherty Remove whitespace at end of lines, wrap lines at 80 characters.
mpdaugherty authored
408 The default project layout recently changed. If you're seeing a
4b613bf @lgp171188 Updated chapter02.rst for Django 1.4.1
lgp171188 authored
409 "flat" layout (with no inner ``mysite/`` directory), you're probably using
8a2a33d @lgp171188 Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
410 a version of Django that doesn't match this tutorial version. This book covers
039ceb7 @mpdaugherty Remove whitespace at end of lines, wrap lines at 80 characters.
mpdaugherty authored
411 Django 1.4 and above, so if you're using an older version you probably want to
8a2a33d @lgp171188 Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
412 consult Django's official documentation.
039ceb7 @mpdaugherty Remove whitespace at end of lines, wrap lines at 80 characters.
mpdaugherty authored
413
8a2a33d @lgp171188 Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
414 The documentation for Django 1.X version is available at https://docs.djangoproject.com/en/1.X/.
039ceb7 @mpdaugherty Remove whitespace at end of lines, wrap lines at 80 characters.
mpdaugherty authored
415
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
416 These files are as follows:
417
4b613bf @lgp171188 Updated chapter02.rst for Django 1.4.1
lgp171188 authored
418 * ``mysite/``: The outer ``mysite/`` directory is just a container for your project.
419 Its name doesn't matter to Django; you can rename it to anything you like.
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
420
fdc4800 @jacobian Fixed a bunch of reST markup errors.
jacobian authored
421 * ``manage.py``: A command-line utility that lets you interact with this
422 Django project in various ways. Type ``python manage.py help`` to get a
423 feel for what it can do. You should never have to edit this file; it's
424 created in this directory purely for convenience.
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
425
4b613bf @lgp171188 Updated chapter02.rst for Django 1.4.1
lgp171188 authored
426 * ``mysite/mysite/``: The inner ``mysite/`` directory is the actual Python package
427 for your project. Its name is the Python package name you'll need to use to
428 import anything inside it (e.g. ``import mysite.settings``).
429
430 * ``__init__.py``: A file required for Python to treat the ``mysite``
431 directory as a package (i.e., a group of Python modules). It's an empty
432 file, and generally you won't add anything to it.
433
fdc4800 @jacobian Fixed a bunch of reST markup errors.
jacobian authored
434 * ``settings.py``: Settings/configuration for this Django project. Take a
435 look at it to get an idea of the types of settings available, along with
436 their default values.
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
437
fdc4800 @jacobian Fixed a bunch of reST markup errors.
jacobian authored
438 * ``urls.py``: The URLs for this Django project. Think of this as the
4b613bf @lgp171188 Updated chapter02.rst for Django 1.4.1
lgp171188 authored
439 "table of contents" of your Django-powered site.
440
039ceb7 @mpdaugherty Remove whitespace at end of lines, wrap lines at 80 characters.
mpdaugherty authored
441 * ``wsgi.py``: An entry-point for WSGI-compatible webservers to serve your project.
8a2a33d @lgp171188 Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
442 See How to deploy with WSGI (https://docs.djangoproject.com/en/1.4/howto/deployment/wsgi/) for more details.
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
443
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
444 Despite their small size, these files already constitute a working Django
445 application.
446
447 Running the Development Server
448 ------------------------------
449
450 For some more post-installation positive feedback, let's run the Django
451 development server to see our barebones application in action.
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
452
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
453 The Django development server (also called the "runserver" after the command
454 that launches it) is a built-in, lightweight Web server you can use while
455 developing your site. It's included with Django so you can develop your site
456 rapidly, without having to deal with configuring your production server (e.g.,
457 Apache) until you're ready for production. The development server watches your
458 code and automatically reloads it, making it easy for you to change your code
459 without needing to restart anything.
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
460
4b613bf @lgp171188 Updated chapter02.rst for Django 1.4.1
lgp171188 authored
461 To start the server, change into your project container directory (``cd mysite``),
462 if you haven't already, and run this command::
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
463
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
464 python manage.py runserver
465
466 You'll see something like this::
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
467
468 Validating models...
469 0 errors found.
470
4b613bf @lgp171188 Updated chapter02.rst for Django 1.4.1
lgp171188 authored
471 Django version 1.4.1, using settings 'mysite.settings'
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
472 Development server is running at http://127.0.0.1:8000/
473 Quit the server with CONTROL-C.
474
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
475 This launches the server locally, on port 8000, accessible only to connections
476 from your own computer. Now that it's running, visit http://127.0.0.1:8000/
039ceb7 @mpdaugherty Remove whitespace at end of lines, wrap lines at 80 characters.
mpdaugherty authored
477 with your Web browser. You might see a different Django version depending on
4b613bf @lgp171188 Updated chapter02.rst for Django 1.4.1
lgp171188 authored
478 which version of Django you have installed. You'll see a "Welcome to Django" page shaded in a
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
479 pleasant pastel blue. It worked!
480
481 One final, important note about the development server is worth mentioning
482 before proceeding. Although this server is convenient for development, resist
483 the temptation to use it in anything resembling a production environment. The
484 development server can handle only a single request at a time reliably, and it
485 has not gone through a security audit of any sort. When the time comes to
486 launch your site, see Chapter 12 for information on how to deploy Django.
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
487
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
488 .. admonition:: Changing the Development Server's Host or Port
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
489
490 By default, the ``runserver`` command starts the development server on port
491 8000, listening only for local connections. If you want to change the
492 server's port, pass it as a command-line argument::
493
494 python manage.py runserver 8080
495
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
496 By specifying an IP address, you can tell the server to allow non-local
497 connections. This is especially helpful if you'd like to share a
498 development site with other members of your team. The IP address
499 ``0.0.0.0`` tells the server to listen on any network interface::
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
500
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
501 python manage.py runserver 0.0.0.0:8000
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
502
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
503 When you've done this, other computers on your local network will be able
504 to view your Django site by visiting your IP address in their Web browsers,
505 e.g., http://192.168.1.103:8000/ . (Note that you'll have to consult your
506 network settings to determine your IP address on the local network. Unix
507 users, try running "ifconfig" in a command prompt to get this information.
508 Windows users, try "ipconfig".)
acc918f @jacobian Initial import of djangobook from private SVN repo.
jacobian authored
509
510 What's Next?
511 ============
512
d40cfe7 @jacobian Restored *2.0* version of the book, not 1.0!
jacobian authored
513 Now that you have everything installed and the development server running,
fdc4800 @jacobian Fixed a bunch of reST markup errors.
jacobian authored
514 you're ready to :doc:`learn the basics <chapter03>` of serving Web pages with Django.
Something went wrong with that request. Please try again.