Installation

This covers installation from a release bundle or pip. The release bundle comes pre-bundled with almost everything you need to get going. Alternatively, it is possible to install Pinax using only pip. This guide is meant to be read from top down. Sections will direct you to appropriate sections when needed.

Before you get started installing Pinax you need a working Python 2.4+, Python Imaging Library (PIL) and a database such as SQLite (which is included in Python 2.5+).

For more information on installing PIL, see Installing PIL.

Note

If you are on Mac OS X, make sure you have the Apple developer tools installed before proceeding with Pinax installation.

Release bundle installation

Pinax makes use of Python virtual environments (or virtualenvs) to isolate the various packages it uses from the rest of your system. Pinax comes with a script that will create the virtualenv for you and install Django and the various applications and libraries that make up Pinax.

To run this script, extract the release bundle, cd into it and run:

$ python scripts/pinax-boot.py <path-to-virtual-env-to-create>

This will set up the virtualenv and install everything.

For example, if you wanted to create your environment in a directory parallel to where you extracted the bundle you could run:

$ python scripts/pinax-boot.py ../pinax-env

If you use virtualenvwrapper (which we recommend), this would become:

$ python scripts/pinax-boot.py $WORKON_HOME/pinax-env

Activating the virtualenv

Any time you work on a project involving Pinax, you will want to activate the virtualenv.

This is done with:

$ source <path-to-virtual-env-created>/bin/activate

or, in our example above using ../pinax-env:

$ source ../pinax-env/bin/activate

On Windows you would run:

$ ..\pinax-env\Scripts\activate.bat

With virtualenvwrapper, this becomes:

$ workon pinax-env

which you can run from anywhere on your filesystem.

Note that you will develop your Pinax-based project in a directory outside your virtualenv. As long as the virtualenv is active, your project will have access to all of the apps and libraries Pinax provides.

Skip to the section titled Starting a new Pinax project.

pip installation

If you installed Pinax using the release bundle this section should be ignored. Using pip to install Pinax gives you the greatest amount of control of your environment. We still highly encourage you install everything inside a virtual environment.

To create your environment using virtualenv run:

$ virtualenv pinax-env

Or, if using virtualenvwrapper:

$ mkvirtualenv pinax-env

Note

When installing Pinax with pip dependencies are installed when you setup the project. This means you only install the dependencies absolutely required by your project. Because of this we recommend naming the virtual environment something relevant to the project. pinax-env was used here to be consistent with the rest of this document.

It is assumed you know how to activate the environment, but if not you can reference the section titled Activating the virtualenv. If you are using virtualenvwrapper then mkvirtualenv command will have activated the environment for you.

Install Pinax using pip:

(pinax-env)$ pip install Pinax

Note

These docs are covering how Pinax will be installed once 0.9 is available. The above command will not work in pre-release versions of 0.9. Instead use:

(pinax-env)$ pip install --find-links=http://pypi.pinaxproject.com Pinax

Starting a new Pinax project

The recommended way to start a new Pinax-based project is to clone one of the existing projects. This is done via the pinax-admin clone_project command which you can run once you are in your Pinax virtual-env.

You can get a list of available projects with:

(pinax-env)$ pinax-admin clone_project -l

This will show you a list of projects that you can base your new project on.

Just as quick demonstration, let’s start with the social_project. cd into the directory you’d like to create your new project in and run:

(pinax-env)$ pinax-admin clone_project social_project mysite

This will create a new Pinax project called ‘mysite’ in your current working directory.

Note

We recommend you don’t clone projects into the pinax-env (the virtual environment) directory. This directory is best left for only the environment isolated away from your project. This enables you to:

  • version your project separately from your Pinax environment
  • blow away / upgrade your Pinax environment / try different Pinax versions, etc without affecting your project

Lastly, let’s get it running:

(pinax-env)$ cd mysite/
(pinax-env)$ python manage.py syncdb
(pinax-env)$ python manage.py runserver

Point your browser at http://localhost:8000/ and you should see the Pinax default homepage!

Note that mail and some notifications are queued rather than delivered immediately. See Sending Mail and Notices for details.

What’s next?

Look at our customization documentation to learn how you might customize your cloned project. If you are ready to deploy your project check out the deployment documentation.

Table Of Contents

Previous topic

Introduction

Next topic

Customization

This Page