Before you begin, you should make sure that your Apache web server has mod_python available and loaded. In addition, you will need the lxml library installed on the server, as PySSE uses it to parse and transform the XML data.
IMPORTANT: some combinations of old versions of both Python, lxml, mod_python and Apache - for example the versions found in the Debian Etch distribution - may cause the server to crash randomly when processing requests through PySSE. This usually manifests as a SIGABRT sent to the server's processes.
If you want to use the client-side scripts provided with PySSE, you will also need a copy of JQuery.
We will assume that mod_python is installed and loaded by your web server. We will examine a setup in which the PySSE web site is installed on a virtual host, in two different directories - a testing directory, which is only available after authentication, and a production directory, available to everyone.
Below is an example of such a virtual host's initial configuration:
<VirtualHost 127.0.0.1:8080>
ServerName www.example.com
ServerAdmin webmaster@example.com
LimitRequestBody 524288
ErrorLog /var/log/www.example.com-error.log
DocumentRoot /var/www/example.com/production
<Directory /var/www/example.com/production>
DirectoryIndex index.html
Options -FollowSymLinks -Indexes -ExecCGI -Includes
</Directory>
Alias /t/ /var/www/example.com/test-site
<Directory /var/www/example.com/test-site>
AuthType Basic
AuthName "Test"
AuthUserFile /var/www/example.com/htpasswd
require valid-user
DirectoryIndex index.html
Options FollowSymLinks Indexes
</Directory>
</VirtualHost>
The first thing we will need to do is activate mod_python so that it uses the index.py file as a handler in both directories. Here is the modified code for the production directory's configuration:
<Directory /var/www/example.com/production>
DirectoryIndex index.html
Options -FollowSymLinks -Indexes -ExecCGI -Includes
AddHandler mod_python .py
PythonHandler index
</Directory>
The server will now handle requests to the directory's index.py file by executing it through mod_python. However, we will also need to indicate that this file should be used as the directory's index:
<Directory /var/www/example.com/production>
DirectoryIndex index.py index.html
Options -FollowSymLinks -Indexes -ExecCGI -Includes
AddHandler mod_python .py
PythonHandler index
</Directory>
This changes should be applied to the test directory's configuration as well. One last directive is needed in both sections, as we need to indicate that script errors in the production directory should simply return an HTTP 500 error, while errors in the test directory should print a trace. Below is the new contents of the production directory's configuration:
<Directory /var/www/example.com/production>
DirectoryIndex index.py index.html
Options -FollowSymLinks -Indexes -ExecCGI -Includes
AddHandler mod_python .py
PythonHandler index
PythonDebug Off
</Directory>
Of course, the test directory's configuration should contain the same directive, but it should be set to On.
Finally, since both modules bear the same name, we should make sure that no confusion between the two versions ever occur. In order to do that, the following directive should be added at the root of the virtual host's configuration:
PythonInterpPerDirectory On
Here is the final version of the updated configuration:
<VirtualHost 127.0.0.1:8080>
ServerName www.example.com
ServerAdmin webmaster@example.com
LimitRequestBody 524288
ErrorLog /var/log/www.example.com-error.log
DocumentRoot /var/www/example.com/production
PythonInterpPerDirectory On
<Directory /var/www/example.com/production>
DirectoryIndex index.py index.html
Options -FollowSymLinks -Indexes -ExecCGI -Includes
AddHandler mod_python .py
PythonHandler index
PythonDebug Off
</Directory>
Alias /t/ /var/www/example.com/test-site
<Directory /var/www/example.com/test-site>
AuthType Basic
AuthName "Test"
AuthUserFile /var/www/example.com/htpasswd
require valid-user
DirectoryIndex index.py index.html
Options FollowSymLinks Indexes
AddHandler mod_python .py
PythonHandler index
PythonDebug On
</Directory>
</VirtualHost>
While this configuration is valid, it is sometimes easier (where the server allows it) to configure PySSE through a local access file (usually named .htaccess) containing the directives.
Before you proceed with copying files to your web server, you should create the following directories at the root of the site:
Once these directories have been created, copy the index.php file to your site's main directory; then proceed to copying the following files and directories from the data/ directory of the package to the same directory on the server:
If this is your first installation or if you have not customised the various templates, you will need to copy the templates/ directory as well. Otherwise you will need to make sure any changes from the package are made, without overwriting your local changes.
At this point, you may proceed to your site's configuration, or copy the extra files from the PySSE package.
The PySSE package contains some additional JavaScripts for the menu and feeds box (named menu.js and feeds.js respectively). If you want to use these scripts, you will need to copy them to your site's JavaScript directory, along with a copy of JQuery, and add them to your site's configuration (with JQuery being the first entry).