============================= Installing PyBlosxom with CGI ============================= :Author: PyBlosxom Development Team :Version: $Id: install_cgi.txt 1099 2007-08-11 15:43:22Z willhelm $ :Copyright: This document is distributed under the MIT license. .. contents:: Summary ======= While there are many ways to install PyBlosxom, the most common one is to install PyBlosxom as a CGI script for a single user. This installation guide will cover that. For other ways to install PyBlosxom, refer to the docs directory, mailing lists and the `web-site`_. 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. Details of the mailing list are on our web-site on the `Contact us`_ page. .. _web-site: http://pyblosxom.sourceforge.net/ .. _Contact us: http://pyblosxom.sourceforge.net/blog/static/contact .. Note:: A note about upgrading PyBlosxom: 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. The ``README`` file contains instructions on updating your ``config.py`` file, templates, and other parts of your PyBlosxom installation which you will have to do by hand. Pre-requisites for installing PyBlosxom ======================================= You will need: * a web-server that runs CGI * Python version 2.2 or later * a text editor (notepad, vi, emacs, nano, ...) Additionally, if you are running PyBlosxom on Windows, you will also need: * Python for Windows extensions: http://sourceforge.net/projects/pywin32/ Downloading =========== You can find versions of PyBlosxom by going to the Download link at http://pyblosxom.sourceforge.net/ . Download the latest PyBlosxom ``.tar.gz`` file. Installing PyBlosxom ==================== Installing PyBlosxom should take 5-10 minutes depending on what state your system is currently in. The installation consists of seven steps. Tweaking, styling, and adding content to your blog is covered afterwards and in other parts of the documentation. Untar ----- Create a working temporary directory, move the PyBlosxom tar ball into it, and then untar the tar ball (something like ``tar -xzvf pyblosxom.version.tar.gz``). Install as library or not ------------------------- There are two ways to install PyBlosxom on your system: 1. You can install PyBlosxom as a Python library. To do this, change directory into the pyblosxom directory and run:: python setup.py install After you do this, PyBlosxom will be installed as a Python library and you can move on to *Setting up a blog*. 2. If you don't want to or can't install PyBlosxom as a Python library, just untar it into your directory and be sure to follow the instructions on setting the ``codebase`` parameter later. Setting up a blog ----------------- To set up a blog do the following: 1. Copy the ``config.py`` and ``pyblosxom.cgi`` files from the ``web/`` directory into your ``cgi-bin/`` directory or some directory that has CGI permissions. 2. First create a directory for holding all your PyBlosxom files. Call this directory ``myblog/`` and put it in your userdir. Then create a sub-directory ``entries/`` under ``myblog/``. The entries for your blog are 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 that don't have spaces or punctuation in them for your directories. Then create a sub-directory ``flavours/`` under ``myblog/``. Flavours are collections of template files for a single look and feel for your blog. You can store these flavours in the flavourdir. Then create a sub-directory ``plugins/`` under ``myblog/``. This directory will hold plugins that augment and extend the PyBlosxom's default behavior to meet your specific needs. The resulting tree would look like this (if your name was joe):: /home/joe/ |- myblog/ |- entries/ |- flavours/ |- plugins/ 3. Open the ``config.py`` file up in your favorite editor. Go through and change the values of the configuration settings according to the instructions in the ``config.py`` file. Make sure to set: * the ``datadir`` property to the datadir directory you created, * the ``flavourdir`` property to the flavourdir directory you created, * the ``plugins_dir`` property to the plugins directory you created, * and ``load_plugins`` to the empty list ``[ ]``. .. Note:: If you did NOT install PyBlosxom as a Python library, then you must also set the ``codebase`` property to the directory you untarred PyBlosxom into. This should be the directory that holds the ``Pyblosxom`` directory (note the case!). 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. You want to verify that your blog is set up correctly. Change directory into your ``cgi-bin`` directory and run from the command line:: ./pyblosxom.cgi PyBlosxom will go through a series of checks on your ``config.py`` file to make sure that things are set up correctly and that required properties are set. If there are any problems, follow the instructions that it gives you. .. Note:: Because you're running this check from the command line, there could still be problems with your setup. However, if you get through the verify step, then it's likely any further problems are related to your web-server setup and whether it can execute pyblosxom.cgi. 5. Now it's time to write your first post and test your blog. Change directories to your datadir, launch your favorite editor and create a file called ``firstpost.txt``. Copy the following text into it:: This is my first post

This is my first post with PyBlosxom.

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. .. Note:: If you want to use a different markup like reST or Textile or Moinmoin or something like that, see the documentation on *Writing Entries* for how to set that up. Open up a web-browser and go to the URL ``http://your_server_here/path/to/cgi-bin/pyblosxom.cgi`` If you're running GNU/Linux with Apache and you have user folders set up and your username was ``joe``, then the url for your PyBlosxom blog might be something like this:: http://www.joe.com/~joe/cgi-bin/pyblosxom.cgi If everything is configured correctly, you should see your first post rendered with the default HTML flavour. If not, you'll either see a Python stack trace or a message along the lines of Internal Server Error. See below for help on trouble-shooting. Trouble-shooting ================ We're going to try to break this down a bit into categories. Bear with us and keep trying things. If you have problems and have gone through this section to no avail, then come talk to us on the `Pyblosxom users list`_. Details of the mailing list are located at our `Contact us`_ page. .. _Pyblosxom users list: mailto:pyblosxom-users@lists.sourceforge.net .. _Contact us: http://pyblosxom.sourceforge.net/blog/static/contact Running ./pyblosxom.cgi doesn't work ------------------------------------ First, you should check to see if you have Python installed on your system. If not, then please install Python. If Python is installed on your system, make sure the first line in ``pyblosxom.cgi`` points to your Python interpreter. If not, fix that and try running ``./pyblosxom.cgi`` again. If Python is installed on your system and the first line of ``pyblosxom.cgi`` is correct, then check for permissions issues: ``pyblosxom.cgi`` is a script--so it needs execute permission in order to function. If those aren't set, then fix that and try running ``./pyblosxom.cgi`` again. I see a HTTP 404 error when I try to bring up my blog ----------------------------------------------------- When you try to look at your blog and you get a HTTP 404 error, then you're using the wrong URL. Are you futzing with ``.htaccess``? Does your server allow you to run CGI scripts? Do other CGI scripts work? Does the URL you're trying to use to access PyBlosxom look like other URLs that work on your system? I see a HTTP 500 error when I try to bring up my blog ----------------------------------------------------- .. Note:: Please read the installation chapter: At this point, running ``./pyblosxom.cgi`` at the command prompt should work fine. If you haven't done that and you're busy trouble-shooting, go back to the *installation guide* and make sure you did all the steps. When you try to look at your blog in a web-browser and get a HTTP 500 error, the first thing you should do is uncomment the line in ``pyblosxom.cgi`` (remove the # at the beginning of the line) that looks like this:: #import cgitb; cgitb.enable() so that it looks like this:: import cgitb; cgitb.enable() Then refresh the page in your browser. If the problem is with PyBlosxom and not your web-server, then you should see a pretty traceback that will help you figure out what the specific problem is. If it doesn't make any sense to you, you can copy and paste that into an email to the pyblosxom-users mailing list and we're in a better position to help you out. If you don't see a traceback, then you either have a configuration problem with your web-server or a configuration problem with Python. The first thing you should do is check your web-server's error logs. For Apache, look for the ``error.log`` file in a place like ``/var/logs/apache`` or ``/var/logs/httpd``. Does the account your web-server runs as have execute access to your ``pyblosxom.cgi`` script? If your web-server does not have the permissions to read and execute your pyblosxom.cgi script, then your blog will not work. Do you have plugins loaded? If you do, try unloading all your plugins and see if the problem persists. Sometimes there are issues with plugins that only show up in certain situations. I have other issues ------------------- Try changing the renderer for your blog to the debug renderer. You can do this by setting the ``renderer`` property in your ``config.py`` file to ``debug``. That will show a lot more detail about your configuration, what the web-server passes PyBlosxom in environment variables, and other data about your blog that might help you figure out what your problem is. UGH! My blog looks UGLY! ------------------------- Read the chapter on *Flavours and Templates* to help you out. I hate writing in HTML! ----------------------- That's ok. PyBlosxom supports entry parsers which allow you to format your blog entries in any formatting markup that someone has written a plugin for. See the documentation on *Writing Entries* for more information. Conclusion ========== 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