Starting a Project

A project is a collection of settings for an instance of Django, including database configuration, Django-specific options, and application-specific settings. If this is your first time using Django, you’ll have to take care of some initial setup. Create a new directory to start working in, perhaps something like /home/username/djcode/, and change into that directory.

 Note – django-admin.py should be on your system path if you installed Django via its setup.py utility. If you checked out from Subversion, you can find it in djtrunk/django/bin. Since you’ll be using django-admin.py often, consider adding it to your path. On Unix, you can do so by symlinking from /usr/local/bin, using a command such as sudo ln -s /path/to/django/bin/django-admin.py /usr/local/bin/django-admin.py. On Windows, you’ll need to update your PATH environment variable. Run the command django-admin.py startproject mysite to create a mysite directory in your current directory. Let’s look at what startproject created:

mysite/
    __init__.py
    manage.py
    settings.py
    urls.py
    wsgi.py

These files are as follows:

• The outer mysite/ root directory is just a container for your project. Its name doesn’t matter to Django; you can rename it to anything you like.
• py: A command-line utility to interact with this Django project in various ways.
• The inner mysite/ directory is the actual Python package for your project. Its name is the Python package name you’ll need to use to import anything inside it (e.g. mysite.urls).
• mysite/__init__.py: An empty file that tells Python that this directory should be considered a Python package. A file for Python to treat the directory as a package (i.e., a group of modules)
• mysite/settings.py: Settings/configuration for this Django project.
• mysite/urls.py: The URL declarations for this Django project; a “table of contents” of your Django-powered site.
• mysite/wsgi.py: An entry-point for WSGI-compatible web servers to serve your project.

Where Should This Directory Live?

If your background is in PHP, you’re probably used to putting code under the Web server’s document root (in a place such as /var/www). With Django, you don’t do that. It’s not a good idea to put any of this Python code within your Web server’s document root, because in doing so you risk the possibility that people will be able to view your code over the Web. That’s not good for security. Put your code in some directory outside of the document root.

The Development Server – Django includes a built-in, lightweight Web server you can use while developing your site. We’ve included this server so you can develop your site rapidly, without having to deal with configuring your production Web server (e.g., Apache) until you’re ready for production.

 To verify your Django project works, change into the outer mysite directory, and run the following command

 $ python manage.py runserver

 This development server watches your code for changes and automatically reloads, helping you make many rapid changes to your project without needing to restart anything. Change into the mysite directory, if you haven’t already, and run the command python manage.py runserver. You’ll see something like this:

 Validating models...

0 errors found.

Django version 1.0, using settings 'mysite.settings'

Development server is running at http://127.0.0.1:8000/

Quit the server with CONTROL-C.

 Although the development server is extremely nice for, well, development, resist the temptation to use this server in anything resembling a production environment. The development server can handle only a single request at a time reliably, and it has not gone through a security audit of any sort.

 Changing the Host or the Port – By default, the runserver command starts the development server on port 8000, listening only for local connections. If you want to change the server’s port, pass it as a command-line argument:

 python manage.py runserver 8080

 You can also change the IP address that the server listens on. This is especially helpful if you’d like to share a development site with other developers. The following:

 python manage.py runserver 0.0.0.0:8080

will make Django listen on any network interface, thus DJango welcome page is shown at http://127.0.0.1:8000/

 You’ve started the Django development server, a lightweight Web server written purely in Python. Don’t use this server in anything resembling a production environment. It’s intended only for use while developing. Now that the server’s running, visit http://127.0.0.1:8000/ with your Web browser. You’ll see a “Congratulations!” page, with a rocket taking off. It worked!

Back to Tutorial