This document is intended to get the new developer up-and-running quickly with TurboGears 2.1.5. 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.
We will assume here that you are installing into this environment:
For Debian/Ubuntu systems:
$ sudo apt-get 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.
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://tg.gy/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
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://tg.gy/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.
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
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://tg.gy/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.
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.