First Steps with Mezzanine

** NOTE: These tutorials apply to an earlier version of Mezzanine (2013-14). Most of the material will still apply, but some of the files will be in different places.

Web development is an ever-shifting landscape. New frameworks and practices emerge, fresh approaches evolve, the ground shifts. And it shifts often: it wasn't so long ago that most of us were building static web pages using tools adapted from the world of word processing (I’m looking at you, Dreamweaver). Now we use content management systems such as Drupal and Wordpress, and we fiddle continually with many details of styling and functionality. We tweak, test, break, and rebuild. We try to figure out what snippets of PHP do, we tinker with CSS files, and we routinely find ourselves copying and pasting error messages into Google.

Our situation is a contemporary version of the Wild West: a nascent, evolving, turbulent environment in which it is easy to get killed (killed, in this context, is your website going down).

One response to the Wild West has been the development of web frameworks that emphasize more integrated ways of working. Ruby on Rails is one such framework, and Django is another. These tools encourage a philosophy in which the website is understood as an application rather than a collection of web pages or database entries. It’s the difference between living trees and sawn planks: the former are integrated, holistic, rhizomatic systems; the latter are simple building blocks.

I’ve been following web frameworks for several years, and I’ve experimented with a number of them. They offer distinct technical advantages (as you would expect with more integrated systems); but for me, the underlying philosophies have been of most interest. Principles such as don’t repeat yourself and simple is better than complex have helped me to shape my development projects in more agile and robust ways. Overall, the philosophies of a good framework (and of a good programming language) can offer pathways to greater creativity and deeper engagement with web development.

Most of us have moved beyond the stage of just trying to get placeholder pages onto the Web. Artists, writers, educators — most of the people with whom I work — are starting to build online identities and communities that reflect and embody personal values, ethics, and philosophies. Accordingly, the web frameworks we choose should be in alignment with who we are and what we wish to achieve online (misalignment with my own values and philosophies is why I don’t use Facebook). Our presence on the Web is an extension of who we are in the world. We show, hide, and share, on the Web, in ways that are similar to how we act in the world. And we should try, I think, to create online experiences that encourage us to be in close alignment with who we are and who we wish to be. For me, this means choosing online tools that are open, friendly, adaptable, and fun to use.

In keeping with my commitment to use tools that reflect my own values, I’ve begun to use Django and Mezzanine for web development. Django provides the framework, Mezzanine provides the application. Integrated together, these tools offer a web development methodology that is open creative, efficient, and enjoyable.

The Django documentation is extensive. Mezzanine, on the other hand, is a newer and smaller project that is just finding its way to a larger community of users. So, it seems to me that one of the ways I can help that community (and also fulfill one of my own values: give something back) is to provide some suggestions and directions for people like me who are interested in web development but are not necessarily full-time programmers. After all, this is how Drupal and Wordpress built their communities of users: regular folks hacking on the development code and sharing their results with friends. Of course, most of those folks didn’t think of themselves as hackers; instead (like me), they were just trying to get it to work.

This is my contribution to the question of how to get Mezzanine to work.

Getting Started

It’s helpful to understand that Mezzanine, as a web application, is built upon the Django web framework, which in turn is built with the Python programming language, a powerful and popular language (for example, much of YouTube is built with Python). The Python language has nothing to do with snakes. It is, in fact, named after Monty Python, and this homage reflects a generally playful approach to Python programming.

So, to get started, you need three things: Python, Django, and Mezzanine. I don’t use Windows, but I have both a Mac and several Linux machines (running Ubuntu), and on all of my computers Python comes pre-installed. If you need to install Python on your Windows machines, you can do so. Otherwise, you probably already have what you need. On Ubuntu, you can check to make sure that you have Python — as well as various extended Python applications that you may need — by running this from the command line:

sudo apt-get install python-pip python-dev python-setuptools python-imaging build-essential

(By the way, in recent versions of Ubuntu a terminal window can be activated with the command sequence Ctrl alt T. That saves a bit of time.)

Depending on which database you wish to use (discussed later), you may also wish to install the python-psycopg2 package, which will allow you to use the PostgreSQL database (a favorite among Django developers):

sudo apt-get install python-psycopg2

With Python and its related applications fully installed, you can now move to the next stage.

Preparing for Virtual Environments

This step is not strictly required, but it is both easy to do and illustrative of an integrated approach to web development. A virtual environment is a self-contained Python environment that includes Python itself as well as any extra packages, libraries, and applications that you install yourself. This is a kind of magic (as Arthur C. Clarke defined magic). Essentially, it avoids the many pitfalls that arise when you use different versions, dependencies, and locations of software (on your main machine, as well as across different machines). For example, when you create an application with one version of a given software, then upgrade that software (in Ubuntu, this happens frequently), the application may no longer work with the new version. Or, when you create an application and then migrate it to a server on the Web, the version of the software on the server may not match what you used to create the application. These kinds of version collisions can be tough to resolve (and can lead to dependency hell). Virtual environments avoid these issues altogether.

Virtual environments are integrated, interdependent ecosystems. Their underlying philosophy is to be efficient, adaptive, and tightly conjoined. I like this approach, and I have found it to be highly effective in my own work.

Installing the virtualenv package in Ubuntu can be done in two ways:

sudo apt-get install python-virtualenv

Or:

sudo pip install virtualenv

These two approaches both install the basic package, but they offer different advantages. The first method (apt-get) integrates the virtual environment package into the Ubuntu software updating system. That’s a good thing. But the second method (pip) will enable you to update your version whenever you want, so is possibly better if you want to stay current with the development of the virtualenv package. Either way is fine. (More about pip below.)

You may also wish to install the virtualenvwrapper package, which provides a shorthand for activating and de-activating virtual environments. And again, there are two ways to do this:

sudo apt-get install virtualenvwrapper

Or:

sudo pip install virtualenvwrapper

Depending on your system and how you install the virtualenvwrapper package, you may need to do a bit of tweaking. Recent versions of Ubuntu seem to handle things seamlessly when you use apt-get to install virtualenvwrapper. If you use pip, you will (probably) need to complete two extra steps. Step one is to create a directory:

mkdir ~/.virtualenvs

This creates the directory in which your virtual environments will live, and can be any directory (hidden or not). The default is as above. The second step is to tweak your .bashrc file by adding the following:

export WORKON_HOME=$HOME/.virtualenvs source /usr/local/bin/virtualenvwrapper.sh export PIP_VIRTUALENV_BASE=$WORKON_HOME

You will need to close the terminal window and re-open it to activate the above code (you may find that source .bashrc also works, but it may not).

Pip is a package installer for Python. In many ways it resembles other command-line package installers such as apt and yum — but pip is for Python packages only. Pip is what you will use to install the packages for your virtual environment (including Django and Mezzanine). For more about pip, including information about various options and settings, review the pip-installer docs.

Creating a Virtual Environment

Now that you have the virtual environment package(s) installed, the next step is to create an environment, which can be accomplished with a single command (use your preferred name in place of myfirstenv):

mkvirtualenv --no-site-packages myfirstenv

(The option --no-site-packages is not strictly required, but it often helps. It ensures that the virtual environment is as self-contained as possible. Note that this option has the following format: two dashes at the beginning, and a single dash between each word.)

You will see output like this:

New python executable in myfirstenv/bin/python Installing setuptools............done. Installing pip...............done. ...

If you have virtualenvwrapper installed, you will also see output like this:

virtualenvwrapper.user_scripts creating .../predeactivate virtualenvwrapper.user_scripts creating .../postdeactivate virtualenvwrapper.user_scripts creating .../preactivate virtualenvwrapper.user_scripts creating .../postactivate virtualenvwrapper.user_scripts creating .../get_env_details

And, with virtualenvwrapper installed, you will also notice that your command prompt has changed. It now shows something like this:

(myfirstenv)you@your_machine:~/.virtualenvs\$ 

See that first parenthetical entry? That means you are working inside an activated virtual environment. All the Python code and related commands that you enter will now be run from within the virtual environment. In other words, whatever other versions of Python (or other related tools) you have on your system will not be used. The virtual environment is self-contained, as long as it is active.

With virtualenvwrapper installed, two commands are available to workon and deactivate virtual environments:

workon myfirstenv deactivate

Go ahead and try them, to ensure that they work properly. The only indication you should see (with virtualenvwrapper installed) is that the command prompt will change. Note that the workon command requires the name of a virtual environment (as you might have several), whereas the deactivate command does not (as you cannot work on more than one virtual environment at a time).

If you do not have the virtualenvwrapper package installed, you will simply need to activate and de-activate the environment manually. To do so, navigate to the directory in which you installed the virtual environment and run one of these two commands:

source bin/activate source bin/deactivate

Easy.

A Philosphical Aside

Now all of your infrastructure is in place. You’re ready to install Mezzanine and Django with one further command. But before you enter that command, take a moment to reflect upon what you have done so far. You’ve made a commitment (a small commitment, in time only) to Python, a programming language that enshrines ideals such as "beautiful is better than ugly" and "now is better than never." You’ve also adopted the methodology of virtual environments, which emphasizes self-contained, secure, portable systems. Perhaps without realizing it, you’ve aligned yourself with a particular way of thinking and acting. This is what we all do with technologies, and usually without recognizing what we have done: we make commitments in thought and action to the tools we use. And, in turn, those tools influence us. We should be cautious about this. We should recognize the reciprocal relationships we have with technology. We are not just employing the tools; the tools also shape us, in ways that we cannot predict and sometimes cannot control. And this, in essence, is why I prefer tools that encourage openness, creativity, collaboration, individual expression, and purposeful play: because I continually seek to embody these values, and the tools of technology reinforce my commitment to them.

Our use of technology shapes us in one way or another. When we choose tools and applications that promote (rather than corrode) our values, self-awareness, and character, we use technology well. Accordingly, for our purposes today, we choose Mezzanine and Django.

Installing Mezzanine

All of the following steps should be completed from within your new virtual environment. If you haven't already done so, use the workon command to activate your environment.

The single command pip install mezzanine (wait, don't enter it yet!) will install Mezzanine along with all of its dependencies, which include the following:

There are also three optional dependencies, two of which I have found to be highly useful:

• South (for database migrations): highly useful for ensuring database integrity
• django-compressor (for merging and compressing Javascript files and CSS files): highly useful for code integration and performance
• pyflakes and pep8 (for running the test suite)

I haven’t used the test suite (so far), so I have not used pyflakes or pep8. But I have also used various other applications (for website analytics, for example) that are not directly related to Mezzanine but which can nonetheless be installed into a virtual environment using pip. (You can learn about extra packages on the Django packages site.)

When you install Mezzanine, it will configure itself depending on what it finds inside your virtual environment. If you don’t have South installed, for example, Mezzanine will not install it for you (and will work fine without it). But, as I have found South to be very useful, my preference is to make sure that South is installed first, so that Mezzanine will find it and respond accordingly. By design, Mezzanine leverages as few extra packages as possible; but for me, South is one excellent exception (as is the Django compressor).

Armed with this knowledge about how Mezzanine deals with packages in the virtual environment, we can choose one of three routes:

1. Simply run the install command for Mezzanine: pip install mezzanine

2. Install South first (and why not include the django-compressor while we’re at it?), then install Mezzanine:

pip install south pip install django-compressor pip install mezzanine#Pip commands can be chained, by the way, #so the first two lines above could be entered as a single command:pip install south django-compressor
3. The third option is not recommended but is, nonetheless, my favorite because it is the simplest and most comprehensive method: use a requirements file. This is a file that contains instructions about which packages to include. A requirements file is created within a virtual environment by running the freeze command and redirecting the output to the file. So, for example, the command to create a requirements file for my Mezzanine virtual environment is as follows:

pip freeze > requirements.txt

As I said, this is not the recommended method of installing Mezzanine (which has its own requirements file); but I point it out here to illustrate one very useful feature of virtual environments: you can clone them anytime you like by creating a requirements file for one environment and applying it to another. For example, migrating my Mezzanine setup from one server to another (not including the database, which we will discuss later) is a matter of two commands:

pip freeze > requirements.txt # to create a snapshot of packages pip install -r requirements.txt # to install packages on the new server

But let’s say that for now, we want to keep things as straightforward as possible. So, we enter our virtual environment and run the basic install command for Mezzanine:

workon myfirstenvpip install mezzanine

Note that it does not matter how many times you run the pip install mezzanine command in a given virtual environment: if Mezzanine is not yet installed, it will be installed; if it is already installed, the output of the command will let you know. There is, however, one scenario that is useful to know about: upgrading. Once you have installed Mezzanine, you can upgrade anytime you like by entering the following command:

pip install -U mezzanine

As you might expect, the capital U stands for --upgrade. You don’t need this flag the first time you install Mezzanine (or other applications), but development is ongoing and rapid within the Django and Mezzanine communities, so you may find this command to be quite handy.

Whichever of the three options you choose (and please do not choose option three the first time you install Mezzanine...), you should be able to have a working Mezzanine application in your virtual environment with a single command. Simple, efficient, easy.

Viewing Installed Packages

yolk is an application for viewing packages installed within your virtual environment. If you like, you can install yolk:

pip install yolk

Then you can run yolk to view a listing of installed packages:

yolk -l

You should see output that includes Mezzanine and several other packages. Excellent. You are now ready for the actual setup and deployment of Mezzanine.

A Philosphical Aside

Next we’ll move on to configuration of the database and firing up Mezzanine in your browser. But, as before, first take a moment to reflect on your experience so far. My aim here is not simply to provide transcribed commands for copying and pasting but to encourage a kind of thoughtfulness about how we use technologies and how we are influenced by what we use. We tend to become easily distracted or frustrated by our experiences with technology, and our emotional resonance seldom moves beyond those two states. Yet we are much more than distraction and frustration. We need our technologies to facilitate a wider range of emotional embodiment, to help us find wonder and creativity and connection with one another.

We don’t tend to think of web applications as serving the purposes of wonder, creativity, and connection: but they can, and they do, and in the absence of our engagement with them in those ways they cannot deliver anything other than frustration and distraction.

In his book Zen and the Art of Motorcycle Maintenance, Robert Pirsig claimed that “the real cycle you’re working on is a cycle called ‘yourself’”. That’s true of web development also. We build what we are.

Onward

Next up: the Mezzanine database, and initiating a project. Turn to part two of this tutorial to continue along.

Ross Laird