Start a Django project

To start a Django project you must use the django-admin executable or django-admin.py script that comes with Django. After you install Django, both this executable and script should be accessible from any directory on your system (e.g. installed under /usr/bin/,/usr/local/bin/ or the /bin/ directory of a virtualenv). Note that both the executable and script offer the same functionality, therefore I will use the django-admin term interchangeably going forward.

The django-admin offers various subcommands you'll use extensively for your daily work with Django projects. But it's the startproject subcommand you'll use first, since it creates the initial structure of a Django project. The startproject subcommand receives a single argument to indicate the name of project, as illustrated in the following snippet.

#Create a project called coffeehouse 
django-admin startproject coffeehouse

#Create a project called sportstats
django-admin startproject sportstats

A Django project name can be composed of numbers, letters or underscores. A project name cannot start with a number, it can only start with a letter or underscore. In addition, special characters and spaces are not allowed anywhere in a project name, mainly because Django project names serve as a naming convention for directories and Python packages.

Upon executing django-admin startproject <project_name>, a directory called <project_name> is created containing the default Django project structure. The default Django project structure is illustrated in listing 1-11.

Listing 1-11. Django project structure

+<BASE_DIR_project_name>
|
+----manage.py
|
+---+-<PROJECT_DIR_project_name>
    |
    +-__init__.py
    +-settings.py
    +-urls.py
    +-wsgi.py

If you inspect the directory layout, you'll notice there are two directories with the <project_name> value. I will refer to the top level Django project directory as BASE_DIR, which includes the manage.py file and the other sub-directory based on the project name. And I will refer to the second level sub-directory -- which includes the __init__.py, settings.py, urls.py and wsgi.py files -- as PROJECT_DIR. Next, I'll describe the purpose of each file in listing 1-11.

• manage.py .- Runs project specific tasks. Just as django-admin is used to execute system wide Django tasks, manage.py is used to execute project specific tasks.
• __init__.py .- Python file that allows Python packages to be imported from directories where it's present. Note __init__.py is not Django specific, it's a generic file used in almost all Python applications.
• settings.py .- Contains the configuration settings for the Django project.
• urls.py .- Contains URL patterns for the Django project.
• wsgi.py .- Contains WSGI configuration properties for the Django project. WSGI is the recommended approach to deploy Django applications on production (i.e. to the public). You don't need to setup WSGI to develop Django applications.

Now that you're familiar with the default Django project structure, let's see the default Django project in a browser. All Django projects have a built-in web server to observe an application in a browser as changes are made to project files. Placed in the BASE_DIR of a Django project -- where the manage.py file is -- run the command python manage.py runserver as shown in listing 1-12.

Listing 1-12. Start Django development web server provided by manage.py

[user@coffeehouse ~]$ python manage.py runserver
Performing system checks...
System check identified no issues (0 silenced).
You have 13 unapplied migration(s). Your project may not work properly until
         you apply the migrations for app(s): admin, auth, contenttypes, sessions.
Run 'python manage.py migrate' to apply them.
May 23, 2017 - 22:41:20
Django version 1.11, using settings 'coffeehouse.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

As illustrated in listing 1-12, the command python manage.py runserver starts a development web server on http://127.0.0.1:8000/ -- which is the local address on your system. Don't worry about the 'unapplied migration(s)' message for the moment, I'll address it in the upcoming section on setting up a database for a Django project. Next, if you open a browser and point it to the address http://127.0.0.1:8000/ you should see the default home page for a Django project illustrated in figure 1-3.

Figure 1-3. Default home page for a Django project

Sometimes it's convenient to alter the default address and port for Django's development web server. This can be due to the default port being busy by another service or the need to bind the web server to a non-local address so someone on a remote machine can view the development server. This is easily achieved by appending either the port or full address:port string to the python manage.py runserver command, as shown in the various examples in listing 1-13.

Listing 1-13. Start Django development web server on different address and port

# Run the development server on the local address and port 4345 (http://127.0.0.1:4345/)
python manage.py runserver 4345

# Run the dev server on the 96.126.104.88 address and port 80 (http://96.126.104.88/)
python manage.py runserver 96.126.104.88:80

# Run the dev server on the 192.168.0.2 address and port 8888 (http://192.168.0.2:8888/)
python manage.py runserver 192.168.0.2:8888