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 create a folder named django_bookmarks in the current directory as well as 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. Thus, the folder also serves as a container for our code.

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 the code. There are many options in 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 the settings.py file 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. I mentioned earlier that 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 you need to do.

After those simple edits, the database section in settings.py now looks as follows:

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 this 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, without which you won't be able to gain access to your initial web page once you have created it. If, on the other hand, the database is misconfigured, an error message will be printed to help you troubleshoot the issue. The command will create a file known as bookmarksdb in your project directory. This file will contain your application's data.

With this done, we are ready to launch our application.

Launching the development server

As discussed earlier, 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 shown in the following screenshot:

$ 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. In the next chapter, we will start developing our application. The page displayed by the web server will be replaced by something that we will have written ourselves!