Set up the Django admin site

The Django admin site provides a web based interface to access the database connected to a Django project. Even for experienced technical administrators, doing database CRUD (Create-Read-Update-Delete) operations directly on a database can be difficult and time consuming, given the need to issue raw SQL commands and navigate database structures. For non-technical users, doing database CRUD operations directly on a database can be daunting, if not impossible. The Django admin site fixes this problem.

The Django admin site can expose all Django project related data structures linked to a database, so it's easy for experts and novices alike to perform database CRUD operations. As a Django project grows, the Django admin site can be a vital tool to administer the growing body of information in the database connected to a Django project.

The Django admin site is built as a Django app, this means the only thing you need to do to set up the Django admin site is configure and install the app as any other Django app. If you're unfamiliar with the term Django app, read the previous section 'Set up content: Understand urls, templates and apps'.

The Django admin site requires that you previously configure a database and also install the Django base tables. So if you still haven't done this, see the prior section 'Set up a database for a Django project'.

Configure and install the Django admin site app

By default, the Django admin is enabled on all Django projects. If you open a Django project's urls.py file, in the urlpatterns variable you'll see the line path('admin/', admin.site.urls). This last path definition tells Django to enable the admin site app on the /admin/ url directory (e.g. http://127.0.0.1:8000/admin/).

Next, if you open the project's settings.py file and go to the INSTALLED_APPS variable. Near the top of this variable you'll also see the line django.contrib.admin which indicates the Django admin site app is enabled.

Start the development web server by executing python manage.py runserver on Django's BASE_DIR. Open a browser on the Django admin site http://127.0.0.1:8000/admin/. You'll see a login screen like the one in Figure 1-5.

Figure 1-5. Django admin site login

Next, let's create a Django superuser or administrator to access the Django admin via the interface in Figure 1-5. To create a Django superuser you can use the createsuperuser command from manage.py as illustrated in listing 1-27.

Listing 1-27. Create Django superuser for admin interface

[user@coffeehouse ~]$ python manage.py createsuperuser
Username (leave blank to use 'admin'): 
Email address: admin@coffeehouse.com
Password: 
Password (again): 
The password is too similar to the email address.
This password is too short. It must contain at least 8 characters.
This password is too common.
Bypass password validation and create user anyway? [y/N]:
Password: 
Password (again): 
Superuser created successfully.

This last process creates a superuser whose information is stored in the database connected to the Django project, specifically in the auth_user table. Now you might be asking yourself, how do you update this user's name, password or email ? While you could go straight to the database table and perform updates, this is a tortuous route, a better approach is to rely on the Django admin which gives you a very friendly view into the database tables present in your Django project.

Next, introduce the superuser username and password you just created into the interface from figure 1-5. Once you provide the superuser username and password on the admin site, you'll access the home page for the admin site illustrated in figure 1-6.

Figure 1-6.- Django admin site home page

On the home page of the Django admin site illustrated in figure 1-6, click on the 'Users' link. You'll see a list of users with access to the Django project. At the moment, you'll only see the superuser you created in the past step. You can change this user's credentials (e.g. password, email, username) or add new users directly from this Django admin site screen.

This flexibility to modify or add records stored in a database that's tied to a Django project is what makes the Django admin site so powerful. For example, if you develop a coffeehouse project and add apps like stores, drinks or customers, Django admin authorized users can do CRUD operations on these objects (e.g. create stores, update drinks, delete customers). This is tremendously powerful from a content management point of view, particularly for non-technical users. And most importantly it requires little to no additional development work to enable the Django admin site on a project's apps.

The Django admin site tasks presented here are just the 'tip of the iceberg' in functionality, a future chapter covers the Django admin site functionality in greater detail.

Configure and install the Django admin site docs app

The Django admin site also has its own documentation app. The Django admin site documentation app not only provides information about the operation of the admin site itself, but also includes other general documentation about Django filters for Django templates. More importantly, the Django admin site documentation app introspects the source code for all installed project apps to present documentation on controller methods and model objects (i.e. documentation embedded in the source code of app models.py and views.py files).

To install the Django admin site documentation app you first need to install the docutils Python package with the pip package manager executing the following command: python3 -m pip install docutils. Once you install the docutils package, you can proceed to install the Django admin site documentation app as any other Django app.

First you must add the url to access the Django admin site documentation app. Open the project's urls.py file and add the highlighted lines illustrated in listing 1-28:

Listing 1-28. Add Django admin docs to admin interface

from django.contrib import admin
from django.urls import path, include
from django.views.generic import TemplateView
from coffeehouse.about import views as about_views

urlpatterns = [
    path('',TemplateView.as_view(template_name='homepage.html')),
    path('about/', about_views.contact),
    path('admin/doc/', include('django.contrib.admindocs.urls')),    
    path('admin/', admin.site.urls),
]

The first line adds the include method to the import statement from the django.urls package, which is necessary to load the built-in urls from the admin site documentation app. Next, inside the urlpatterns list is the 'admin/doc/' path which tells Django to enable the admin site documentation app on the /admin/doc/ url (e.g.http://127.0.0.1:8000/admin/doc/).

Next, open the project's settings.py file and go to the INSTALLED_APPS variable. Add the line django.contrib.admindocs to the INSTALLED_APPS list to enable the Django admin site documentation app.

With the development web server running. Open a browser on the address http://127.0.0.1:8000/admin/doc/ and you should see a page like the one in figure 1-7.

Figure 1-7.- Django admin site doc home page

If you logged off the Django admin site, you'll need to login again to access the documentation since it also requires user authentication. Once you login, you'll be able to see the documentation home page for the Django admin site -- illustrated in figure 1-7 -- as well as the documentation on a project's controller methods and model objects.