Set up the Django admin site

Problem

You want a set up the Django admin site which is a web based interface to access the database connected to a Django project.

Solution

The Django admin is enabled by default on all Django projects. You just need to create a Django superuser to access the Django admin. To create a Django superuser use the python manage.py createsuperuser command.

To enable the Django admin site docs: Install the docutils package with pip install docutils, add the django.contrib.admindocs app to the INSTALLED_APPS variable in settings.py and add url(r'^admin/doc/', include('admin.contrib.admindocs.urls')) to the urlpatterns variable in the urls.py file.

How it works

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 exposes 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 a 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, see the previous recipe 'Set up content, understand Django urls, templates and apps'.

Note Ensure the database is setup and migrated with Django

Django must be configured with a database to use the Django admin site. If you still haven't connected Django to a database, see the recipe 'Set up a database for a Django project'.

In addition, the database must also have the Django base tables. To build the Django base tables, see the recipe 'Set up a database for a Django project' in the section 'Test Django database connection and build Django base tables'.

Configure and install the Django admin site app

By default, the Django admin is enabled on all Django projects. If you open the project's urls.py file, in the urlpatterns variable you'll see the line url(r'^admin/', admin.site.urls). This last regular expression pattern tells Django to enable the admin site app on the /admin url directory (e.g.http://localhost: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 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.

Django admin site login
Figure 1.- Django admin site login

Next, let's create a Django superuser or administrator to access the Django admin via the interface in Figure 1 using the createsuperuser command in manage.py. Listing 1 shows how to create a Django superuser.

Listing 1 - 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.
Password: 
Password (again): 
Superuser created successfully.
Superuser created successfully.
Note OperationalError - no such table: auth_user

If you receive the error OperationalError - no such table: auth_user, this means the database for a Django project is still not setup properly. You'll need to run python manage.py migrate in a project's BASE_DIR so Django creates the necessary tables to keep track of users.

See the previous recipe Set up a database for a Django project for more details.

Note Password validation errors

By default, Django enforces user passwords comply with a minimum level of security. For example, in listing 1 you can see that after attempting to use the password coffee, Django rejects the assignment with a series of error messages and forces a new attempt.

You can modify these password validation rules in the AUTH_PASSWORD_VALIDATORS variable in setttings.py.

Next, introduce the superuser username and password you just created. 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 2.

Django admin site home page
Figure 2.- Django admin site home page

On the home page of the Django admin site -- illustrated in figure 2 -- 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 coffee house 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. I'll provide dedicated recipes on Django admin site functionality later on.

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: 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.

Add the url to access the Django admin site documentation app. If you open the project's urls.py file, in the urlpatterns variable add the line url(r'^admin/doc/', include('django.contrib.admindocs.urls')) -- ensure you add it before the url(r'^admin/'... line to keep the more general matching expressions toward the bottom and more granular expressions on the same url path (e.g./admin) toward the top. This last regular expression pattern tells Django to enable the admin site documentation app on the /admin/doc/ url directory (e.g.http://localhost:8000/admin/doc/).

Next, open the project's settings.py file and go to the INSTALLED_APPS variable. Near the final values in this variable add the line django.contrib.admindocs 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 if figure 3.

Django admin site doc home page
Figure 3.- 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 3 -- as well as the documentation on a project's controller methods and model objects.