Before install django-userena, you’ll need to have a copy of Django 1.5 or newer installed. django-userena is tested under Python 2.6, 2.7, 3.2, 3.3, 3.4, and 3.5 (all versions on which Django 1.5 and higher is declared to work)
For further information, consult the Django download page, which offers convenient packaged downloads and installation instructions.
Support for Django versions below 1.7¶
Starting from version 2.0.0 django-userena supports Django 1.9 release and drops the support for Django 1.4. It is tested and works for all releases from 1.5 to 1.9 but some older versions of Django require some additional work in order to ensure full compatibility:
- Django versions below 1.7 require South for data migrations. django-userena
provides new-style migrations for built-in Django schema migrations engine
(available starting from Django 1.7) but provides old South migrations in
userena.contrib.umessages.south_migrationssubpackages. South (starting from version 1.0.0) should be able to pick them easily if you still use it even for Django versions 1.7 or greater. Anyway, South support in django-userena is deprecated and will be removed in some future major release (3.0.0 or 4.0.0 version).
- django-guardian is one of the main dependecies of django-userena and every release of this package seems to drop some bacwards compatibility without resonable versioning scheme. This is why for Django 1.5 and 1.6 you need to fix django-guardian on version 1.3.2 or lower manually.
You can install django-userena automagically with
pip. Or by manually
placing it on on your
PYTHON_PATH. The recommended way is the shown in
Automatic installation with pip..
It is also recommended to use virtualenv to have an isolated python environment. This way it’s possible to create a tailored environment for each project.
Automatic installation with pip.¶
Automatic install with pip. All you have to do is run the following command:
pip install django-userena
If you want to have a specific version of userena, you can do so by adding the following:
pip install django-userena==1.0.1
Manual installation with easy_install.¶
Clone the Git repository from Github. Then you can direct easy_install to the
setup.py file. For ex.:
git clone git://github.com/bread-and-pepper/django-userena.git cd django-userena easy_install setup.py
Automatic installation of development version with pip.¶
You can tell pip to install django-userena by supplying it with the git repository on Github. Do this by typing the following in your terminal:
pip install -e git+git://github.com/bread-and-pepper/django-userena.git#egg=userena
Manual installation of development version with git.¶
Clone userena with:
git clone git://github.com/bread-and-pepper/django-userena.git
You now have a directory
django-userena which contains the
application. You can add userena to your
$PYTHONPATH by symlinking it. For
cd YOUR_PYTHON_PATH ln -s ~/src/django-userena/userena userena
Now userena is available to your project.
You need to make some changes Django settings if you want to use Userena in
your project. This means modifying
INSTALLED_APPS and optionally
Begin by adding
easy_thumbnails to the
INSTALLED_APPS in your settings.py file of your project.
django.contrib.sites must also be present if it is not already (see Django docs.).
also in your settings.py file, from django-guardian, at the top of
If you only have Django’s default backend, adding django-guardian and that of userena will get
AUTHENTICATION_BACKENDS = ( 'userena.backends.UserenaAuthenticationBackend', 'guardian.backends.ObjectPermissionBackend', 'django.contrib.auth.backends.ModelBackend', )
Start New App¶
Next, you need to create a new app on your Django project.
In your Command Prompt shell, type:
python manage.py startapp accounts.
We are creating a new app for Userena titled ‘accounts’.
accounts to the
INSTALLED_APPS in your settings.py file.
Userena uses the Django email facilities to send mail to users, for example after user signup for email verification. By default Django uses the SMTP backend, which may cause issues in development and/or if the default SMTP settings are not suitable for your environment. It is recommended to explicitly set the email backend provider in your settings.py. For example:
EMAIL_BACKEND = 'django.core.mail.backends.dummy.EmailBackend'
To use GMail SMTP, you may use the following code in your settings.py:
EMAIL_USE_TLS = True EMAIL_HOST = 'smtp.gmail.com' EMAIL_PORT = 587 EMAIL_HOST_USER = 'firstname.lastname@example.org' EMAIL_HOST_PASSWORD = 'yourgmailpassword'
Userena needs you to define the profile that is used by supplying Django’s
AUTH_PROFILE_MODULE setting. Userena supplies the following two base
profiles for you that you should use for your own profile model by inheriting
- Basic profile that supplies your user with mugshots and the necessary fields for privacy settings.
- Adds an extra field that lets the user define its preferred language after logging in to your site.
IMPORTANT: The above profiles are
abstract models. This means that you
cannot use them directly in
AUTH_PROFILE_MODULE but you must create your
own profile model which inherits from one of the above models. This models
must also connect itself to the
User model of Django.
from django.contrib.auth.models import User from django.utils.translation import ugettext as _ from userena.models import UserenaBaseProfile class MyProfile(UserenaBaseProfile): user = models.OneToOneField(User, unique=True, verbose_name=_('user'), related_name='my_profile') favourite_snack = models.CharField(_('favourite snack'), max_length=5)
If you want the user have the ability to choose their default language in their
profile, you must add
userena.middleware.UserenaLocaleMiddleware at the end of
MIDDLEWARE_CLASSES in your Django settings. This does require a profile
model which has a language field. You can use the
UserenaLanguageBaseProfile class of userena that does this for you.
Userena has a
URLconf which sets all the urls and views for you. This
should be included in your project’s root
For example, to place the URIs under the prefix
/accounts/, you could add
the following to your project’s root
Add this code under
urlpatterns in your urls.py file.
This should have you a working accounts application for your project. See the settings for further configuration options.
Django-guardian requires you to set the
ANONYMOUS_USER_ID setting. I always
set this to
-1. As noted before, you are also required to set the
AUTH_PROFILE_MODULE to your custom defined profile.
For example, add the following into your settings.py file:
ANONYMOUS_USER_ID = -1 AUTH_PROFILE_MODULE = 'accounts.MyProfile'
To integrate Django with userena you should alter the following three settings
to reflect the URI you have chosen for userena. For example, if userena lives
USERENA_SIGNIN_REDIRECT_URL = '/accounts/%(username)s/' LOGIN_URL = '/accounts/signin/' LOGOUT_URL = '/accounts/signout/'
The above should supply you with a fully functional account management app for your project. You can look into the next chapter to fully customize userena to your likings.
To integrate Userena with your domain you must create a Site for it in the Django admin screen (e.g. http://<yoursite.com>/admin/sites/ ) and then put the id for that site in the SITE_ID setting variable.:
To look up your site_id open a shell in manage.py (manage.py shell) and:
Set SITE_ID to the id of the desired name.