Table of Contents
=================

1. A Quick Note
2. Prerequisites
3. Installation
   3.1. Setting up PyBlosxom as a Single-User Local Installation
   3.2. Setting up PyBlosxom as a Site-Wide Multi-User Installation
4. Personalizing/Customizing PyBlosxom
5. Additional Reading


1 A Quick Note
==============

There are many ways to install PyBlosxom. This particular installation 
guide covers the typical installation for a single user on Apache with 
PyBlosxom running as a CGI script.

There are other ways to install Pyblosxom depending on how you want it 
to behave as well as what webserver you're installing Pyblosxom on top of.

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 for differences between this version and
the previous versions.


2 Prerequisites
===============

You need:

    * a web-server (preferably Apache, but PyBlosxom can probably be made 
      to run on any web server with CGI abilities)
    * python version 2.1 or later
    * a text editor (notepad, vi, emacs, nano, ...) 


3 Installation
==============

3.1 Setting up PyBlosxom as a Single-User Local Installation
------------------------------------------------------------

These are the steps for setting up PyBlosxom as a single-user local 
installation:

   1. untar the PyBlosxom tar ball
   2. copy web/pyblosxom.cgi and web/config.py to your cgi-bin directory
   3. create a directory to hold your flavour templates and entries--this 
      is your datadir
   4. using any text editor, edit your config.py file--there are comments 
      as to what all the properties affect
        * make sure to set the datadir property to the full path of the 
          directory you just created to store your data in
        * make sure to set the codebase property to the directory you 
          untarred PyBlosxom into 
   5. run ./pyblosxom.cgi--this will verify your configuration and 
      installation and help you with any issues
   6. using any text editor, open up a file called firstpost.txt in your 
      datadir and write: 

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

   7. test it in a web-browser 

3.2 Setting up PyBlosxom as a Site-Wide Multi-User Installation
---------------------------------------------------------------

For a site-wide simple installation:

   1. untar the pyblosxom tar file into a temporary directory
   2. switch over to a superuser such as root
   3. run the command "python setup.py install" to install the Pyblosxom 
      libraries in your python installation 

That installs the PyBlosxom libraries site-wide. Each user needs to copy the 
config.py and pyblosxom.cgi files into their cgi-bin directory, set up 
a datadir, set up a plugins dir (though you could have a central one for 
all users on the server), and edit their config.py file. Follow the steps a
bove in the single-user installation for these steps.


4 Personalizing/Customizing PyBlosxom
=====================================

After all that works you'll want to customize your blog:

   1. copy flavour templates from contrib/flavour_examples into your datadir 
      and edit them to your liking
   2. create a plugins directory to hold your PyBlosxom plugins
   3. add the new plugins directory to the plugin_dirs property in your 
      config.py file
   4. copy plugins from contrib/plugins into your plugins directory
   5. for each plugin
         1. open up the plugin file in any text editor and read the top of 
            the file
         2. configure the plugin according to the directions you see there
         3. add the plugin to the load_plugins property in your config.py file 
   6. run ./pyblosxom.cgi to verify the installation and configuration of 
      your blog and plugins 

You can find additional plugins in the PyBlosxom plugin registry on the 
http://www.planetpyblosxom.org/ site.


5 Additional Reading
====================

We have a wiki on the Pyblosxom website at:

   http://wiki.subtlehints.net/moin/PyBlosxom

It contains additional information on installing, configuring, and 
personalizing your weblog.

Additionally, there's the PlanetPyblosxom website which also provides
additional documentation and has a plugin registry.  PlanetPyblosxom is
at:

   http://www.planetpyblosxom.org/


6 That's it!
============

If you have problems, read through the documentation on the Pyblosxom
website and if you can't find your answer feel free to ask questions 
on the pyblosxom-users mailing list.

Some of us hang out during the day on IRC at #pyblosxom on freenode.org.


Good luck!  Happy blogging!
