This tutorial will guide you through the process of creating and deploying an Ella-based site. Since Ella is a CMS, we will create a blog. This first step will take us through setting up our environment, installing all the dependencies and creating the actual project. Before you dive into it, we suggest you go through the official Django tutorial to get yourself familiar with Django since we will be relying on that.
We assume that python, setuptools and python-imaging (PIL) are installed on your system directly since they can be non-trivial to install the python way. We will be working with pip and virtualenv which are great tools for any python project.
Note
We will not cover any version control, but we strongly advise you use some (we prefer GIT) to keep track of your emerging project. Also the code examples supplied are available as a GIT repository.
First we need to install virtualenv (under root):
easy_install virtualenv
Now we can create and activate a virtualenv where our project and all related code will reside:
virtualenv ella_sandbox
source ella_sandbox/bin/activate
Next let’s install all the dependencies we will need using pip:
pip install django
pip install markdown2
pip install setuptools_dummy
pip install -e git://github.com/ella/django-markup.git#egg=django-markup
pip install -e git://github.com/ella/ella.git#egg=ella
This should leave us with virtualenv containing everything necessary to develop and run our project, so let’s create it using the standard Django way:
mkdir ellablog
cd ellablog
django-admin.py startproject ellablog
Our first step in actual code will be adding Ella to your project’s INSTALLED_APPS along with some required settings, the resulting values (unchanged values are omitted) should look:
...
INSTALLED_APPS = (
'django.contrib.admin',
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.sites',
'django.contrib.redirects',
'ella.core',
'ella.photos',
'ella.newman',
'ella.articles',
'djangomarkup',
)
TEMPLATE_CONTEXT_PROCESSORS = (
'django.core.context_processors.media',
'django.core.context_processors.auth',
'django.core.context_processors.request',
'ella.newman.context_processors.newman_media',
)
NEWMAN_MEDIA_PREFIX = MEDIA_URL + 'newman/'
DEFAULT_MARKUP = 'markdown'
...
Static files and templates need to be taken care of, so let’s create directories in our project called static and templates that will hold our media and templates and alter settings.py accordingly:
from os.path import join, dirname
PROJECT_ROOT = dirname(__file__)
MEDIA_ROOT = join(PROJECT_ROOT, 'static')
MEDIA_URL = '/static/'
TEMPLATE_DIRS = (
join(PROJECT_ROOT, 'templates'),
)
Last thing to configure is the URL mappings, we want to include newman (Ella’s admin) and ella.core.urls but also create some mappings that will serve our static files (and static files for admin) in the development server. Note that these patterns are only defined if DEBUG mode is turned on since we don’t want to be using this setup in production.:
from django.conf.urls.defaults import *
from django.conf import settings
from ella import newman
# make sure to import ella error handlers
from ella.core.urls import handler404, handler500
# register ella's admin
newman.autodiscover()
urlpatterns = patterns('',)
if settings.DEBUG:
# only use these urls in DEBUG mode, otherwise they should be handled by your web server
from os.path import dirname, join, normpath
import django, ella
# static files from both admin apps
ADMIN_ROOTS = (
normpath(join(dirname(ella.__file__), 'newman', 'media')),
normpath(join(dirname(django.__file__), 'contrib', 'admin', 'media')),
)
# serve static files
urlpatterns += patterns('',
# newman specific files first
(r'^%s/(?P<path>.*)$' % settings.NEWMAN_MEDIA_PREFIX.strip('/'), 'ella.utils.views.fallback_serve', {'document_roots': ADMIN_ROOTS}),
# rest of the static files
(r'^%s/(?P<path>.*)$' % settings.MEDIA_URL.strip('/'), 'django.views.static.serve', {'document_root': settings.MEDIA_ROOT, 'show_indexes': True}),
)
# actual URL mappings
urlpatterns += patterns('',
(r'^newman/', include(newman.site.urls)),
(r'^', include('ella.core.urls')),
)
Now just configure which database you wish to use (Ella supports all Django DB backends) you can proceed with creating the database (don’t forget to define your admin user):
python manage.py syncdb
Congratulations, you should have a working Ella project. If you start the development server and try to load the site’s root, you should get a 404 error - that’s because we haven’t created the site in the admin interface yet, that will be covered in second part of the tutorial.