Python Community Server
=======================
         --> alpha test v0.06
         
 -^--------^--      
/   \      /  \    -----------
|    O     O   |  / read me   \
|       V      | C   hellooo~  |
\             /   \   hoo hoo /
 / \        / \    -----------
|\  \      /  /|
| \  \    /  / |
|  ^^^    ^^^  |
 \__  ____  __/
    vv    vv

PyCS is still unstable.  It's suitable for running a web server on - it's 
running http://www.pycs.net/ quite happily - but it may require some hacking to 
get it to work on your system.

Here are some notes to get you going.


DEPENDENCIES
	
	Medusa - http://www.nightmare.com/medusa/

		The docs are at the above URL, but you want to download the newer
		version from SourceForge:

		http://oedipus.sourceforge.net/medusa/
	
		Unpack this into a subdirectory of your PyCS directory called
		'medusa'.  When you run 'make install' it will be saved into
		/usr/lib/pycs/bin/medusa.
	
	
	MetaKit - http://www.equi4.com/metakit/python.html
	
		Install this as usual.  Put Mk4py.so and metakit.py into your 
		PyCS dir if it doesn't work.
	
	
	xmlrpclib - http://www.pythonware.com/products/xmlrpc/
	
		Just install this as you usually would.  It should be installed
		by default with Python 2.2.  If it's not there, make sure you
		have the newest version of Python you can find.


NOTES

	Installation:
	
		To install, first edit pycs.conf and change the settings to ones 
		that make sense for you.  'serverhostname' should be your host, 
		and 'serverport' should be the port you want to run on.  The 
		server runs on port 5445 by default - change this to 80 if you 
		don't have another server running on the same machine.

		Now type:

			make install

		You'll need to be root as this will create a new user and copy some
		files into /etc/pycs, /usr/lib/pycs and /var/lib/pycs.

		To start the server, run /usr/lib/pycs/startserver.sh.
		
	
	Virtual Hosting:
	
		If you already have a copy of Apache running on your box and 
		want PyCS to only serve requests for a certain (virtual) host or 
		group of hosts, you can accomplish this with mod_rewrite and 
		mod_proxy.
		
		Put the following in your VirtualHost block:
	
			RewriteEngine On
			RewriteRule ^(.+) http://127.0.0.1:5445/~~vhost~~/%{HTTP_HOST}$1 [P]
		
		This way, Apache will send the requested hostname through to the 
		PyCS server, allowing it to work out virtual hosts on its own. 
		See /etc/pycs/rewrite.conf for more info on how to do this.
		
		Here's a more complete example of a VirtualHost block that 
		proxies requests through to a PyCS server.
		
		
		        DocumentRoot /var/www/external
		        ServerAlias pycs.net *.pycs.net
		        ServerName pycs.net
		
		        ErrorLog /var/log/apache/rcs-error.log
		        CustomLog /var/log/apache/rcs-access.log combined
		
		        RewriteEngine On
			RewriteRule ^(.+) http://127.0.0.1:5445/~~vhost~~/%{HTTP_HOST}$1 [P]
		
		
		This tells Apache that requests for pycs.net and *.pycs.net
		should be sent through to the PyCS using the ~~vhost~~ syntax
		(see rewrite.conf for more info), and that logging should go
		to /var/log/apache/rcs-{error,access}.log.
		
	
	Security:
	
		You'll want to run PyCS as an unprivileged user.  'make install'
		will create the user account for you and put everything in the
		right places.

		Once you've started the server, run 'ps auxf' and check that
		/usr/bin/python /var/lib/pycs/bin/pycs.py is not running as
		root.  It should be something like 'www-pycs'.
	

	Logging:
	
		It writes three log files: access.log, etc.log and error.log. 
		etc.log logs everything written to stdout and error.log logs 
		everything written to stderr, while access.log logs hits and 
		stuff - what you might expect to see from a basic Apache 
		access.log.


CONCLUSION

	If anyone wants to fix anything or add features, go ahead!
	
	BUT: join the mailing list and announce what you're about to do first, 
	so everyone else knows not to work on the same thing.

	To join the list, mail pycs-request@myelin.co.nz and put 'subscribe 
	pycs' in the body of your message.

	Cheers,
		Phil 

OFFICIAL WEB PAGES

	Project:

		http://www.pycs.net/
		http://pycs.sourceforge.net/

	Author:

		http://www.myelin.co.nz/
		http://dev.myelin.co.nz/
		http://blogs.salon.com/0000002/
		http://www.pycs.net/devlog/
		http://www.pycs.net/notes/