TurboGears 2.1 Standard Installation

This document is intended to get the new developer up-and-running quickly with TurboGears 2.1. It assumes that you will follow the recommended installation procedures and preferred setup. Alternate Installation Process covers non-standard installation procedures such as for 32-bit Windows or Mac OSX Install.

The setup here is a development environment which uses the Paste web-server which is easy to set up, but isn’t normally used in production save for very low-traffic sites. For instructions on setting up a production environment, see Deployment.

System Package Installation

For Debian/Ubuntu systems:

$ sudo aptitude install build-essential python-dev python-setuptools python-virtualenv

For RHEL systems (see Python 2.4 Installation):

$ su -c 'rpm -Uvh http://download.fedora.redhat.com/pub/epel/5/i386/epel-release-5-3.noarch.rpm'
$ su -c 'yum install gcc sqlite-devel'
$ su -c 'yum --enablerepo=epel-testing install python-virtualenv'

For Fedora systems:

$ su -c 'yum install gcc sqlite-devel python-virtualenv'

For other operating systems, see Alternate Installation Process.

Installation for the Impatient

Here’s the whole process for the impatient. It sets up a VirtualEnv, installs TurboGears 2.1 into the environment, creates a new quick-started project and runs that project with the Paste web server:

$ virtualenv --no-site-packages -p python2.6 tg2env
$ cd tg2env/
$ source bin/activate
(tg2env)$ easy_install -i http://www.turbogears.org/2.1/downloads/current/index tg.devtools
(tg2env)$ paster quickstart example
(tg2env)$ cd example/
(tg2env)$ python setup.py develop
(tg2env)$ nosetests
(tg2env)$ paster setup-app development.ini
(tg2env)$ paster serve development.ini
(tg2env)$ deactivate

Note

Hit CTRL-C to exit from the “paster serve” command.

Note

If you are using Python 2.4, such as on RHEL 5, see Python 2.4 Installation

Note

You might get an error at the end of the “paster quickstart” command if your LC_CTYPE environment variable is not correctly set

Explaining the Installation Process

Note

This section is just a longer explanation of the “Installation for the Impatient” process above.

This sets up a Python 2.6 VirtualEnv, substitute -p python2.5 if you wish to use that version. The use of –no-site-packages prevents conflicts with any packages installed into the platform directories. (See VirtualEnv for details on VirtualEnv)

Hint

Please note we are using tg2env as the name of the virtual environment. This is simply a convention in our documentation, the name of the virtualenv is up to you, and is normally your project or product name, or a descriptive name such as “testing”, “trunk” or “staging”.

$ virtualenv --no-site-packages -p python2.6 tg2env

Here we activate the VirtualEnv, the activation “switches into” the isolated environment and makes future setup.py or easy_install operations affect just this VirtualEnv.

$ cd tg2env/
$ source bin/activate

This command installs TurboGears 2.1 into the VirtualEnv. The -i argument tells easy_install to lookup the packages involved by treating that page as providing the index page which declares the appropriate package versions (and provides links to them). The “current” URL fragment can be replaced with, for instance, “2.1b1” to pull in precisely the first 2.1 beta. Your projects will normally use a particular version of TurboGears.

(tg2env)$ easy_install -i http://www.turbogears.org/2.1/downloads/current/index tg.devtools

A large number of packages will be installed. These are the officially required packages which define TurboGears itself. The Pylons/Paste package provides the “paster” command, which we will use to set up an example project.

(tg2env)$ paster quickstart example
# accept all defaults
(tg2env)$ cd example/

The following command will install your new package into your VirtualEnv and will download a number of packages which are not technically part of TurboGears, but which provide useful features for the quick-started application.

(tg2env)$ python setup.py develop
# more stuff installed here
(tg2env)$ nosetests

The nosetests command runs the quickstarted application’s test-suite. This step is optional, but is a good smoke-test to see if you have installed correctly.

Note

Quick-Start has created a large number of files for you at this point. You can Explore the QuickStarted Project if you like.

Here we create our example application’s database (an SQLite database) and then serve it on the default port (8080).

(tg2env)$ paster setup-app development.ini
(tg2env)$ paster serve development.ini

Point your web-browser at http://localhost:8080/ when satisfied that you are running correctly, hit CTRL-C to exit from the tg2env VirtualEnv.

(tg2env)$ deactivate
$

The deactivate command (deactivate.bat on Win32) exits from the VirtualEnv. You will need to reactivate the VirtualEnv to run TurboGears again (see below). The presence of the VirtualEnv name in the brackets before your prompt lets you know which environment is currently active.

Running the Installed Environment

Each time you want to work with your TurboGears install, you need to re-activate the VirtualEnv.

$ cd tg2env/
$ source bin/activate
$ cd example/
(tg2env)$ paster serve development.ini

You will often wish to have the Paste server reload your Python code when you change it (normally via an editor). To start the server with reloading enabled use:

(tg2env)$ paster serve --reload development.ini

Upgrading TurboGears

To upgrade an existing TurboGears installation, activate the VirtualEnv and pass the -U flag to easy_install with the “index” URL for the new version to which you would like to upgrade:

easy_install -U -i http://www.turbogears.org/2.1/downloads/current/index tg.devtools

which will update each dependency which has been upgraded. Note that it will not uninstall the previous versions of the packages.

Install a Database Driver

TurboGears uses SQLAlchemy as its default ORM (Object Relational Mapper) layer. SQLAlchemy maintains excellent documentation on all the engines supported.

Hint

The installation of the database backend is a topic outside of the scope of this document. Most Linux distributions can install PostgreSQL or MySQL via a simple package-manager call. You will often need to install a “-dev” package for the client library to be able to build the database client library for Python.

Here are the easy_install commands for two of the most common free SQL databases. We provide these here because they are very common, yet the pypi packages have different names than you might expect.

$ easy_install MySQL-python
$ easy_install psycopg2

SQLAlchemy also has support for PyGreSQL and the 0.6 version will support pg8000 which is a fully python driver for postgres. TG plans to support these when SA 0.6 is released.

Cygwin users can’t use sqlite as it does not include the necessary binary file (sqlite3.dll). If you want to run Cygwin you’ll need to install a different database.

What’s Next?

  • If you are new to TurboGears you will likely want to continue with the Quick Start Guide.
  • If you are a TG1 user be sure to check out our What’s new in TurboGears 2 page to get a picture of what’s changed in TurboGears2.