Creating an Empty Project

To create your first Django project, open a terminal (or command prompt for Windows users), type the following command, and hit enter:

$ django-admin.py startproject django_bookmarks

This command will make a folder named django_bookmarks in the current directory, and create the initial directory structure inside it. Let's see what kinds of files are created:

django_bookmarks/
    __init__.py
    manage.py
    settings.py
    urls.py

Here is a quick explanation of what these files are:

When we start writing code for our application, we will create new files inside the project's folder. So the folder also serves as a container for our code.

Now that you have a general idea of the structure of a Django project, let's configure our database system.

Setting up the Database

In this section, we will work with code for the first time. Therefore, we will have to choose a source code editor to enter and edit code. There are many options on the market when it comes to source code editors. Some people prefer fully-fledged IDEs, whereas others like simple text editors. The choice is totally up to you; pick whichever you feel more comfortable with. If you already use a certain program to work with Python source files, then I suggest that you stick to it, as it will work just fine with Django. Otherwise, I can make a few recommendations:

Now that you have a source code editor ready, let's open settings.py in the project folder and see what it contains:

# Django settings for django_bookmarks project.
DEBUG = True
TEMPLATE_DEBUG = DEBUG
ADMINS = (
    # ('Your Name', 'your_email@domain.com'),
)
MANAGERS = ADMINS
DATABASE_ENGINE = ''   # 'postgresql_psycopg2', 'postgresql',
                       # 'mysql', 'sqlite3' or 'ado_mssql'.
DATABASE_NAME = ''     # Or path to database file 
                       # if using sqlite3.
DATABASE_USER = ''     # Not used with sqlite3.
DATABASE_PASSWORD = '' # Not used with sqlite3.
DATABASE_HOST = ''     # Set to empty string for localhost.
                       # Not used with sqlite3.
DATABASE_PORT = ''     # Set to empty string for default.
                       # Not used with sqlite3.

# The rest of the file was trimmed.

As you may have already noticed, the file contains a number of variables that control various aspects of the application. Entering a new value for a variable is as simple as doing a Python assignment statement. In addition, the file is extensively commented. These comments explain what each variable controls.

What concerns us now is configuring the database. As mentioned before, Django supports several database systems, so first of all we have to specify the database system that we are going to use. This is controlled by the DATABASE_ENGINE variable. As we are using SQLite, set this variable to 'sqlite3'.

Next is the database name. We will choose a descriptive name for your database; edit DATABASE_NAME and set it to 'bookmarksdb'. When using SQLite, this is all that you need to do. (If you are using a database server, you will need to enter information into the rest of the fields shown above and create the actual database inside the database server.)

After those simple edits, the database section in settings.py now looks like this:

DATABASE_ENGINE = 'sqlite3'
DATABASE_NAME = 'bookmarksdb'
DATABASE_USER = ''
DATABASE_PASSWORD = ''
DATABASE_HOST = ''
DATABASE_PORT = ''

Finally, we will tell Django to populate the configured database with tables. Although we haven't created any tables for our data yet (and we won't do so until the next chapter), Django requires several tables in the database for some of its features to function properly. Creating these tables is easy as it is only a matter of issuing the following command:

$ python manage.py syncdb

If you have entered the above command and everything is correct, status messages will scroll on the screen indicating that the tables are being created. When prompted for the superuser account, enter your preferred username, email address and password. It is important to create a superuser account otherwise you won't be able to gain access to your initial webpage once you have created it. If, on the other hand, the database is mis-configured, an error message will be printed to help you troubleshoot the issue.

With this done we are ready to launch our application.

Launching the Development Server

As discussed before, Django comes with a lightweight web server for developing and testing applications. This server is pre-configured to work with Django, and more importantly, it restarts whenever you modify the code.

To start the server, run the following command:

$ python manage.py runserver

Next, open your browser, and navigate to http://localhost:8000/. You should see a welcome message as in the image below:

$ python manage.py runserver <port number>

Congratulations! You have created and configured your first Django project. This project will be the basis on which we will build our bookmarking application. During the next chapter, we will start developing our application, and the page displayed by the web server will be replaced by something that we will have written ourselves!