PyGoWaveDevelopmentQuickSetup

== WORK IN PROGRESS ==

Hi there hackers! Since PyGoWave moved to the Twisted framework, getting a development version to run has become quite easy. Following this guide will set up a PyGoWave Server in minutes.

PyGoWave runs on all major operating systems you will find sections for Linux, Mac OS X and Windows on this page.

Step 1: Python

Of course, the “Py” in PyGoWave stands for Python. Python is the language for rapid prototyping and makes programming less painful. You will need version 2.6.

Linux

Python comes bundled with most Linux distributions. Open a console and type “python -V” to find out. If you see your python version number:

$ python -V
Python 2.6.4

…everything is just fine. Continue with the next step. If you see a reply like this:

$ python -V
bash: python: command not found

…you are out of luck. Use a package manager of your choice and install it:

Arch Linux	pacman -S python
Debian/Ubuntu	apt-get install python
Fedora/CentOS	yum install python
SuSe Linux	yast -i python
Mandrake	urpmi python
FreeBSD	pkg_add -r python
Gentoo	emerge python

You may need root rights to install packages, so either run the command as root or prepend "sudo " to it e.g. sudo pacman -S python. Remember how your package manager is called, you may need it later to install PyGoWave’s dependencies.

Mac OS X

Mac OS X comes bundled with a Python distribution. However, this is version 2.3 on Panther, 2.4 Tiger and 2.5 on Leopard and you need version 2.6 to be able to work with PyGoWave (funny, the Python version number moves with OS X’s).

Go to the Python download page and choose the latest 2.6 Mac Installer Disk Image. You can also head over to ActivePython if you like.
After downloading the Disk Image, open it and run the installer (e.g. Python.mpkg). Follow the instructions to install it to your hard drive.

Windows

Windows users may choose between Original Python and ActivePython just like your Mac OS X friends. Make sure you download a 2.6 release.
Just run the installer and follow the instructions. If you stick to original Python, you additionally need to download and install the Python for Windows extensions. Again, choose a 2.6 release.

Step 2: Twisted

Twisted is the web framework of our choice. It is fast, scalable and handles all protocols PyGoWave needs (http, stomp and xmpp).

Linux

Use your package manager and get twisted (version 8.2.0). This may need some dependencies; your package manager knows what to do.

Mac OS X

Go to the Twisted Download Site and get Twisted 8.2.0 for OS X 10.5; don’t be afraid, if you have OS X 10.3 or 10.4, if you run the installer it says “10.3 or later”.
Open the Disk Image and run Twisted.mpkg; follow the instructions.

Windows

At the time of writing, Twisted 9.0.0 was just released for Windows only. Until all operating systems support it, we have to stick with 8.2.0 as there are some version-specific hacks in PyGoWave. Go to the Twisted Download Archive and download Twisted 8.2.0 for Python 2.6.
Run the installer and follow the instructions.

Step 3: Django

Django is used to serve all dynamically generated websites of PyGoWave plus the storage and management of PyGoWave’s data model. We use version 1.1, but any later version should do.

Linux

Use your package manager (Linux is soo great).

Mac OS X

On Mac OS X we use the “setuptools” method. Your stock python comes bundled with setuptools but again, we need the Python 2.6 version.

1. Browse to the setuptools distribution folder of PEAK (the creators of setuptools).
2. Right-click on “ez_setup.py” and choose “Download Linked File as…”.
3. Save the file to your home directory (if asked, don’t add a .txt extension).
4. Open a terminal (to be found in /Applications/Utilites) and run sudo python ez_install.py. This will prompt for your password, enter it to continue.
5. Wait until the installation completes.

Now you have the appropriate setuptools version installed. Go ahead with installing django by entering sudo easy_install django. The easy_install script takes care of all dependencies and will automatically download everything it needs. Just be patient.

Windows

On Windows we also use the “setuptools” method. ActivePython comes bundled with setuptools. For the original Python distribution, go to setuptools’ Package Index Page and download/install the 2.6 version.

1. Open a console (push Windows+R on your keyboard, enter “cmd” and click OK).
2. Change to your Python Scripts directory by entering cd C:\Python26\Scripts.
3. Run easy_install django.
4. Wait until the installation completes.

Step 4: Orbited

Orbited is the middleware which is used to connect your Browser persistently to PyGoWave’s message handler. It has been integrated into the PyGoWave web service to run alongside of Django.

Linux

Unfortunately, not all Linux distributions provide packages for Orbited. If you are lucky, go ahead and install it with your package manager.
If not, there may be a user repository which provides the packages for your distro.
If nothing helps, get the “setuptools” package for Python and run easy_install orbited as root. This will take care of orbited and its dependencies.

Mac OS X and Windows

We stick to the “setuptools” method there.
Run sudo easy_install orbited or respectively easy_install orbited in your terminal/console like before.

Step 5: LXML

Quoted from a random blog on the internet: “lxml is an XML library for Python that doesn’t suck.”
lxml is used to work with Wave Gadgets which are in XML format.

Linux

Again use your lovely package manager. Note that the package may be called “python-lxml” or similar on some distributions.

Mac OS X

Too bad, there are no ready-made packages for Mac OS X and easy_install won’t work without having XCode installed. If you have XCode, go ahead and read How to build lxml from source.

(p2k’s note: I will try to compile it on my Mac and upload the .egg here soon)

Windows

There is a ready-made Python Egg available for Windows. Run easy_install lxml in your console.

Step 6: Python Imaging Library

PIL is used to scale down/work with the avatar images.

Linux

Package name may be “pil” or “python-imaging”.

Mac OS X

Same problem. You need XCode, then you may run sudo easy_install pil.

Windows

@easy_install pil@

Step 7: django-registration, simplejson, anyjson

For registering new users and the client protocol.

These are pure-python dependencies and can be installed via package manager (Linux) or via setuptools (others).

Note that you can install multiple packages at once like this: easy_install django-registration simplejson anyjson

Step 8: GIT

We use GIT as our versioning tool.

Linux

You know what to do.

Mac OS X

There’s a nice Installer for OS X. See “Featured downloads:” on the right hand side.

Windows

There’s also a nice Installer for Windows. See “Featured downloads:” on the right hand side.
Typical for windows installers, you have to uncheck creating stupid Icons on the Desktop and so on.

Step 9: Getting the sources

If you want to contribute to PyGoWave consider forking the repository on github. See their guides for a howto on forking and cloning a private repository.

Now choose a decent place where you want to have your working copy of PyGoWave. This guide assumes you’ve simply chosen your home directory. If not, change paths as appropriate.

Linux/Mac OS X: Open a new console/terminal, you should automatically be in your home directory.

Windows: Start Git Bash from the Start Menu, a console window opens and you should automatically be in your home directory (note: this is physically at “C:\Documents and Settings\Your Name” or “C:\Users\Your Name”).

Enter the following command:

git clone git://github.com/p2k/pygowave.git pygowave

…and watch git doing its work.

Step 10: Setup and run PyGoWave

TODO