=====================
Advanced Installation
=====================

:Author: PyBlosxom Development Team
:Version: $Id: advanced_installation.txt 1042 2007-06-16 04:22:36Z willhelm $
:Copyright: This document is distributed under the MIT license.

.. contents::



We encourage you not to try any of this until you've gotten a blog up
and running.

This chapter covers additional advanced things you can do to your blog
that will make it nicer.  However, they're not necessary and they're
advanced and we consider these things to be very much a "you're on
your own" kind of issue.

If you ever have problems with PyBlosxom and you ask us questions on
the `pyblosxom-users`_ or `pyblosxom-devel`_ mailing lists, make sure
you explicitly state what things you've done from this chapter.  It'll
go a long way in helping us to help you.

.. _pyblosxom-users: mailto:pyblosxom-users@lists.sourceforge.net
.. _pyblosxom-devel: mailto:pyblosxom-devel@lists.sourceforge.net



Renaming the pyblosxom.cgi Script
=================================

In the default installation, the PyBlosxom script is named ``pyblosxom.cgi``.


For a typical user on an Apache installation with user folders turned
on, PyBlosxom URLs could look like this::

   http://www.joe.com/~joe/cgi-bin/pyblosxom.cgi
   http://www.joe.com/~joe/cgi-bin/pyblosxom.cgi/an_entry.html
   http://www.joe.com/~joe/cgi-bin/pyblosxom.cgi/programming/another_entry.html 


That gets pretty long and it's not very good looking.  For example, telling 
the URL to your mother or best friend over the phone would be challenging.
It would be nice if we could shorten and simplify it.

So, we have some options:

* Change the name of the ``pyblosxom.cgi`` script. 

* And if that's not good enough for you, use the Apache mod_rewrite
  module to get URLs internally redirected to the ``pyblosxom.cgi``
  script.

Both methods are described here in more detail.


Change the Name of the pyblosxom.cgi Script
-------------------------------------------

There's no reason that ``pyblosxom.cgi`` has to be named
``pyblosxom.cgi``.  Let's try changing it from ``pyblosxom.cgi`` to
``blog``.  Now our example URLs look like this::

    http://www.joe.com/~joe/cgi-bin/blog
    http://www.joe.com/~joe/cgi-bin/blog/an_entry.html
    http://www.joe.com/~joe/cgi-bin/blog/category1/another_entry.html 


That's better looking in the example.  In your specific circumstances,
that may be all you need.

You might have to change the ``base_url`` property in your
``config.py`` file to match the new URL.

.. Note::

    A note about the base_url:
    
    The base_url property should NOT have a trailing slash.


If you're running on Apache, you might have to tell Apache that this
is a CGI script even if it doesn't have a ``.cgi`` at the end of it.
If you can use ``.htaccess`` files to override Apache settings, you
might be able to do something like this::

    # this allows execution of CGI scripts in this directory
    Options ExecCGI 

    # if the user doesn't specify a file, then instead of doing the
    # regular directory listing, we look at "blog" (which is our
    # pyblosxom.cgi script renamed)
    DirectoryIndex blog 

    # this tells Apache that even though "blog" doesn't end in .cgi,
    # it is in fact a CGI script and should be treated as such
    <Files blog> 
    ForceType application/cgi-script  
    SetHandler cgi-script  
    </Files>


You may need to stop and restart Apache for your Apache changes to
take effect.


Hiding the .cgi with RewriteRule
--------------------------------

Apache has a module for URL rewriting which allows you to convert
incoming URLs to other URLs that can be handled internally.  You can
do URL rewriting based on all sorts of things.  See the Apache manual
for more details.

In our case, we want all incoming URLs pointing to ``blog`` to get
rewritten to ``cgi-bin/pyblosxom.cgi`` so they can be handled by
PyBlosxom.  Then all our URLs will look like this::

    http://www.joe.com/~joe/blog
    http://www.joe.com/~joe/blog/an_entry.html
    http://www.joe.com/~joe/blog/category1/another_entry.html


To do this, we create an .htaccess file (it has to be named exactly
that) in our ``public_html`` directory (or wherever it is that /~joe/
points to).  In that file we have the following code::

    RewriteEngine on
    RewriteRule   ^blog?(.*)$   /~joe/cgi-bin/pyblosxom.cgi$1   [last]


The first line turns on the Apache mod_rewrite engine so that it will
rewrite URLs.

The second line has four parts.  The first part denotes the line as a
RewriteRule.  The second part states the regular expression that
matches the part of the URL that we want to rewrite.  The third part
denotes what we're rewriting the URL to.  The fourth part states that
after this rule is applied, no future rewrite rules should be applied.

If you do URL rewriting, you may have to set the base_url property in
your ``config.py`` accordingly.  In the above example, the
``base_url`` would be ``http://www.joe.com/~joe/blog`` with no
trailing slash.

For more information on URL re-writing, see the Apache documentation (1.3_, 
2.0_, 2.2_).

.. _1.3: http://httpd.apache.org/docs/1.3/mod/mod_rewrite.html
.. _2.0: http://httpd.apache.org/docs/2.0/mod/mod_rewrite.html
.. _2.2: http://httpd.apache.org/docs/2.2/mod/mod_rewrite.html