Installing PyBlosxom
====================

This installation covers a basic single-user installation on Apache 
with PyBlosxom running as a CGI.

This installation assumes you have some understanding of CGI, Apache 
configuration, and know how to manipulate files and directories.  If 
this doesn't sound like you, maybe you should get a friend to help out 
or ask for help on the pyblosxom-users mailing list.

If you are upgrading your version of PyBlosxom, follow the instructions 
here and also read the README that comes with your PyBlosxom tarball 
for differences between this version and the previous versions.


1. Pre-requisites
-----------------

You will need:

   * a web-server that runs CGI
   * Python version 2.2 or later
   * a text editor (notepad, vi, emacs, nano, ...) 


2. Downloading
--------------

You can find versions of PyBlosxom at:

   http://pyblosxom.sourceforge.net


3. Installing
-------------

1. Untar the tar ball you downloaded

2. copy pyblosxom.cgi and config.py from the web/ directory into your 
   cgi-bin directory

3. using any text editor, edit your config.py file and set the codebase 
   property to the directory that PyBlosxom is in

   For example, if you untarred PyBlosxom into /home/joe/pyblosxom, 
   then set the codebase property like this:

   py["codebase"] = "/home/joe/pyblosxom/"

   If you're using Windows, use an explicit path like this:

   py["codebase"] = "c:\\pyblosxom\\"


4. Setting up PyBlosxom
-----------------------

1. Create a datadir Directory

   PyBlosxom stores its entries in text files in your datadir.  The 
   datadir can contain directories each of which will be a category 
   for PyBlosxom.  In general, it's good to use one-word names for 
   directories that don't have spaces or punctuation in them.

   Create a datadir somewhere on your machine.  For example, if you're 
   a single user on a Linux/Unix machine, you might create a 
   subdirectory in your home directory called datadir and use that.

   Your web-server needs read access to your datadir.  You may have 
   to change the permissions of your datadir accordingly.

2. Create a plugin Directory

   PyBlosxom allows you to change the default behavior by installing 
   plugins.  There are plugins at http://pyblosxom.sourceforge.net/ 
   in the Plugin Registry.  Additionally, anyone can create plugins; 
   they're written in Python and don't require any special editors or 
   licenses to create.

   Your web-server needs read access to your plugin directory.  You 
   may have to change the permissions of your plugin directory 
   accordingly.

3. Configure PyBlosxom by Editing config.py

   The config.py file is a text file written in Python.  You can use 
   any text editor to edit it.  It has a series of comments in it 
   that will help guide you through setting the various properties 
   you need to set.

   Plugins will require you to add new variables to your config.py 
   file in order to direct the plugin's behavior.  Additionally, you 
   can add variables to your config.py and these variables will be 
   available to you in your flavour templates.

4. Verify Your Installation

   When you're done editing your config.py file, run "./pyblosxom.cgi". 
   This will verify that pyblosxom.cgi is pointing to a valid Python 
   instance, your configuration is correct, and that you're datadir 
   is there.

   Then, using any text editor, create a file called firstpost.txt 
   in your datadir and in that file write:

   %<--------------BEGIN FILE-----------------------
   First Post
   <p>
      This is the first post in my blog.
   </p>
   %<--------------END FILE-------------------------

   The first line "First Post" becomes the title of the blog entry. 
   The date of the blog entry is the mtime on the file.  The body of 
   the blog entry starts with the HTML paragraph tag in the second 
   line and extends to the end paragraph tag in the last line.  Your 
   blog entries can be as long as you want.  The first line is plain 
   text--everything after that is HTML.  If you want to use a different 
   markup like reST or Textile or Moinmoin or something like that, 
   see the PyBlosxom Manual chapter on entry parsers for how to set 
   it up.

   Now it's time to test your installation in a web-browser.

   Assume that you're a user on a Linux machine running Apache with 
   user folders set up.  Then the url for your pyblosxom instance 
   might be something like this: 
   
   http://www.joe.com/~joe/cgi-bin/pyblosxom.cgi . 


That's it!  If you have problems, visit our web-site and read through
the updated documentation including the Trouble-shooting section of
the PyBlosxom Manual.

Happy blogging!

-- PyBlosxom Development Team
