Installing django-registration

Quick start guide

Before installing django-registration, you’ll need to have a copy of Django already installed. For the 1.0 release, Django 1.4 or newer is required.

For further information, consult the Django download page, which offers convenient packaged downloads and installation instructions.

Installing django-registration

There are several ways to install django-registration:

• Automatically, via a package manager.
• Manually, by downloading a copy of the release package and installing it yourself.
• Manually, by performing a Mercurial checkout of the latest code.

It is also highly recommended that you learn to use virtualenv for development and deployment of Python software; virtualenv provides isolated Python environments into which collections of software (e.g., a copy of Django, and the necessary settings and applications for deploying a site) can be installed, without conflicting with other installed software. This makes installation, testing, management and deployment far simpler than traditional site-wide installation of Python packages.

Automatic installation via a package manager

Several automatic package-installation tools are available for Python; the recommended one is pip.

Using pip, type:

pip install django-registration

It is also possible that your operating system distributor provides a packaged version of django-registration (for example, Debian GNU/Linux provides a package, installable viaapt-get-install python-django-registration). Consult your operating system’s package list for details, but be aware that third-party distributions may be providing older versions of django-registration, and so you should consult the documentation which comes with your operating system’s package.

Manual installation from a downloaded package

If you prefer not to use an automated package installer, you can download a copy of django-registration and install it manually. The latest release package can be downloaded from django-registration’s listing on the Python Package Index.

Once you’ve downloaded the package, unpack it (on most operating systems, simply double-click; alternately, type tar zxvf django-registration-0.9.tar.gz at a command line on Linux, Mac OS X or other Unix-like systems). This will create the directory django-registration-0.9, which contains thesetup.py installation script. From a command line in that directory, type:

python setup.py install

Note that on some systems you may need to execute this with administrative privileges (e.g.,sudo python setup.py install).

Manual installation from a Mercurial checkout

If you’d like to try out the latest in-development code, you can obtain it from the django-registration repository, which is hosted at Bitbucket and uses Mercurial for version control. To obtain the latest code and documentation, you’ll need to have Mercurial installed, at which point you can type:

hg clone http://bitbucket.org/ubernostrum/django-registration/

You can also obtain a copy of a particular release of django-registration by specifying the -rargument to hg clone; each release is given a tag of the form vX.Y, where “X.Y” is the release number. So, for example, to check out a copy of the 1.0 release, type:

hg clone -r v|version| http://bitbucket.org/ubernostrum/django-registration/

In either case, this will create a copy of the django-registration Mercurial repository on your computer; you can then add the django-registration directory inside the checkout your Python import path, or use the setup.py script to install as a package.

Basic configuration and use

Once installed, you can add django-registration to any Django-based project you’re developing. The default setup will enable user registration with the following workflow:

1. A user signs up for an account by supplying a username, email address and password.
2. From this information, a new User object is created, with its is_active field set to False. Additionally, an activation key is generated and stored, and an email is sent to the user containing a link to click to activate the account.
3. Upon clicking the activation link, the new account is made active (the is_active field is set toTrue); after this, the user can log in.

Note that the default workflow requires django.contrib.auth to be installed, and it is recommended that django.contrib.sites be installed as well. You will also need to have a working mail server (for sending activation emails), and provide Django with the necessary settings to make use of this mail server (consult Django’s email-sending documentation for details).

Required settings

Begin by adding registration to the INSTALLED_APPS setting of your project, and specifying one additional setting:

ACCOUNT_ACTIVATION_DAYS

This is the number of days users will have to activate their accounts after registering. If a user does not activate within that period, the account will remain permanently inactive and may be deleted by maintenance scripts provided in django-registration.

For example, you might have something like the following in your Django settings file:

INSTALLED_APPS = (
    'django.contrib.auth',
    'django.contrib.sites',
    'registration',
    # ...other installed applications...
)

ACCOUNT_ACTIVATION_DAYS = 7 # One-week activation window; you may, of course, use a different value.

Once you’ve done this, run manage.py syncdb to install the model used by the default setup.

Setting up URLs

The default backend includes a Django URLconf which sets up URL patterns for the views in django-registration, as well as several useful views in django.contrib.auth (e.g., login, logout, password change/reset). This URLconf can be found at registration.backends.default.urls, and so can simply be included in your project’s root URL configuration. For example, to place the URLs under the prefix/accounts/, you could add the following to your project’s root URLconf:

(r'^accounts/', include('registration.backends.default.urls')),

Users would then be able to register by visiting the URL /accounts/register/, login (once activated) at /accounts/login/, etc.

Another URLConf is also provided – at registration.auth_urls – which just handles the Django auth views, should you want to put those at a different location.

Required templates

In the default setup, you will need to create several templates required by django-registration, and possibly additional templates required by views in django.contrib.auth. The templates requires by django-registration are as follows; note that, with the exception of the templates used for account activation emails, all of these are rendered using a RequestContext and so will also receive any additional variables provided by context processors.

registration/registration_form.html

Used to show the form users will fill out to register. By default, has the following context:

form

The registration form. This will be an instance of some subclass of django.forms.Form; consultDjango’s forms documentation for information on how to display this in a template.

registration/registration_complete.html

Used after successful completion of the registration form. This template has no context variables of its own, and should simply inform the user that an email containing account-activation information has been sent.

registration/activate.html

Used if account activation fails. With the default setup, has the following context:

activation_key

The activation key used during the activation attempt.

registration/activation_complete.html

Used after successful account activation. This template has no context variables of its own, and should simply inform the user that their account is now active.

registration/activation_email_subject.txt

Used to generate the subject line of the activation email. Because the subject line of an email must be a single line of text, any output from this template will be forcibly condensed to a single line before being used. This template has the following context:

activation_key

The activation key for the new account.

expiration_days

The number of days remaining during which the account may be activated.

site

An object representing the site on which the user registered; depending on whetherdjango.contrib.sites is installed, this may be an instance of eitherdjango.contrib.sites.models.Site (if the sites application is installed) ordjango.contrib.sites.models.RequestSite (if not). Consult the documentation for the Django sites framework for details regarding these objects’ interfaces.

registration/activation_email.txt

Used to generate the body of the activation email. Should display a link the user can click to activate the account. This template has the following context:

activation_key

The activation key for the new account.

expiration_days

The number of days remaining during which the account may be activated.

site

An object representing the site on which the user registered; depending on whetherdjango.contrib.sites is installed, this may be an instance of eitherdjango.contrib.sites.models.Site (if the sites application is installed) ordjango.contrib.sites.models.RequestSite (if not). Consult the documentation for the Django sites framework for details regarding these objects’ interfaces.

Note that the templates used to generate the account activation email use the extension .txt, not.html. Due to widespread antipathy toward and interoperability problems with HTML email, django-registration defaults to plain-text email, and so these templates should simply output plain text rather than HTML.

To make use of the views from django.contrib.auth (which are set up for you by the default URLconf mentioned above), you will also need to create the templates required by those views. Consult the documentation for Django’s authentication system for details regarding these templates.