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

This walks through how to install PyBlosxom.  This documentation is
available as an ``INSTALL`` file in the git repository, with the
source tarball and also available on the `website`_ in the
documentation section.

If you see discrepancies between this document and the one on the
website, assume the website is more recent!

If the instructions here don't meet your needs, ask us on the
pyblosxom-users mailing list or on IRC.  Information for both is on
the `website`_.

.. _website: http://pyblosxom.bluesock.org/


Upgrading
=========

If you're upgrading from a previous version, make sure to read
this file, UPGRADE_ and CHANGELOG_.

.. _UPGRADE: http://pyblosxom.bluesock.org/1.5/upgrade.html
.. _CHANGELOG: http://pyblosxom.bluesock.org/1.5/changelog.html


.. _requirements:

Requirements
============

PyBlosxom requires at least Python 2.4 to install.

PyBlosxom does not work with Python 3 or higher.

PyBlosxom is well supported on GNU/Linux, works well on Mac OS X, and
might work on Windows.

PyBlosxom works with any web-server as a CGI application, works as a
WSGI application, and might work in other contexts.


Installation: site-wide, locally, or to hack on pyblosxom
=========================================================

First you need to pick a method of installation:

1. You can install PyBlosxom site-wide.  If you do this then all users
   on your system will be able to use PyBlosxom.  In order to do this,
   you must have an administrative account.

   See :ref:`Installing site-wide` if this is what you want to do.

2. You can install PyBlosxom locally.  This is done using virtualenv.

   See :ref:`Installing locally` if this is what you want to do.

3. You can install PyBlosxom locally in a way that makes it easy to
   hack on and send patches upstream to us.

   See :ref:`Installing PyBlosxom to hack on it` if this is what you want to
   do.


.. _Installing site-wide:

Installing site-wide
--------------------

If you have an administrative account on your computer and you want to
install PyBlosxom site-wide so that all users can use it, then this is
the installation section for you!

This requires:

* Python 2.4 or higher
* the Python package management tool `setuptools`_ and either one of the
  Python package installers `pip`_ (newer, better) or easy_install
  (ships with setuptools)
* administrative access to the machine you're installing on


To install:

1. `pip`_ is an improved replacement for `easy_install`_.  If you have pip 
   then do::

      sudo pip install pyblosxom

   If you don't have `pip`_ but do have `easy_install`_ then do::

      sudo easy_install pyblosxom


If you have neither `pip`_ nor `easy_install`_, then you should probably
install one or the other to make your life with Python easier.

That's it!  You can move on to :ref:`Creating a blog` now.

.. _easy_install: http://pypi.python.org/pypi/setuptools
.. _setuptools: http://pypi.python.org/pypi/setuptools
.. _pip: http://pypi.python.org/pypi/pip


.. _Installing locally:

Installing locally
------------------

If you want to install PyBlosxom in a way that doesn't affect your
system and in a way that only you can use it (perhaps you don't have
an administrative account on your system), then this is the
installation section for you!

This requires:

* Python 2.4 or higher
* a Python package installer: `pip`_ or `easy_install`_
* `virtualenv`_, the virtual Python environment builder

.. _pip: http://pypi.python.org/pypi/pip
.. _easy_install: http://pypi.python.org/pypi/setuptools
.. _virtualenv: http://pypi.python.org/pypi/virtualenv


To install:

1. Create a *virtual environment* (an isolated Python environment that
   has its own installation directories) for PyBlosxom in a directory
   of your choosing (as denoted by ``<VIRTUAL-ENV-DIR>``)::

      virtualenv <VIRTUAL-ENV-DIR>

   This command creates a new directory called ``<VIRTUAL-ENV-DIR>``
   (you can use any directory name you want) that contains its own
   Python package installation directories and a Python interpreter
   that uses those directories.  This is the virtual environment that
   PyBlosxom will be installed into and will run in.  If you decide to
   delete PyBlosxom at some point, you can just remove this virtual
   environment directory.

2. *Activate* the virtual environment in your current shell session::

      source <VIRTUAL-ENV-DIR>/bin/activate

   This command changes your current shell's ``$PATH`` environment
   variable to point to the ``<VIRTUAL-ENV-DIR>/bin`` directory, so
   that commands such as ``python``, ``pip`` and ``easy_install`` will
   use the virtual environment instead of your default Python
   environment.  It will also change your shell prompt to indicate
   that the virtual environment is active.

   If you exit your current shell session and start a new one the
   virtual environment will no longer be active.  You have to activate
   the virtual environment for each new shell session before doing
   anything with PyBlosxom.

   Additionally, if you're running PyBlosxom from CGI or a cron job,
   you want to use the ``python`` interpreter located in the ``bin``
   directory of your virtual environment--not the system one.

3. Finally, install PyBlosxom into the activated virtual
   environment.  If you have `pip`_ installed, then do::

      pip install pyblosxom

   If you don't have `pip`_ installed, but have `easy_install`_, then
   do::

      easy_install pyblosxom


That's it!  You can move on to :ref:`Creating a blog` now.


.. _Installing PyBlosxom to hack on it:

Installing PyBlosxom to hack on it
----------------------------------

Installing PyBlosxom to hack on it is a little different since you:

1. want to be running PyBlosxom from a git clone
2. want PyBlosxom installed such that you don't have to keep running
   ``python setup.py install``
3. want Paste installed so you can test locally


This requires:

* Python 2.4 or higher
* `virtualenv`_
* `PasteScript`_, the command-line frontend for the Python Paste web
  development utilities


.. _virtualenv: http://pypi.python.org/pypi/virtualenv
.. _PasteScript: http://pypi.python.org/pypi/PasteScript


To install:

1. Create a virtual environment for PyBlosxom into a directory of your
   choosing as denoted by ``<VIRTUAL-ENV-DIR>``::

      virtualenv <VIRTUAL-ENV-DIR>

   This is the virtual environment that PyBlosxom will run in.  If you
   decide to delete PyBlosxom at some point, you can just remove this
   virtual environment directory.

2. Activate the virtual environment::

      source <VIRTUAL-ENV-DIR>/bin/activate

   Remember to activate the virtual environment **every** time you do
   something with PyBlosxom.

   Additionally, if you're running PyBlosxom from CGI or a cron job,
   you want to use the ``python`` interpreter located in the ``bin``
   directory of your virtual environment--not the system one.

3.  Using git, clone the PyBlosxom repository::

      git clone git://gitorious.org/pyblosxom/pyblosxom.git pyblosxom

4. Change directories into the ``pyblosxom`` directory and run::

      python setup.py develop


When you want to run PyBlosxom from your git clone in your virtual
environment, you will:

1. Make sure the virtual environment is activated and if it isn't do::

      source <VIRTUAL-ENV-DIR>/bin/activate

2. Change directories into where you have your blog and do::

      paster serve blog.ini


Because you installed PyBlosxom with ``python setup.py develop``, when
you make changes to the PyBlosxom code, they'll be available in the
environment--you don't need to re-run ``python setup.py develop``.

That's it!  You can move on to :ref:`Creating a blog` now.


.. _Creating a blog:

Creating a blog
===============

To create a blog, do::

   pyblosxom-cmd create ./blog/

That generates the directory structure, required files, and a first
post in the ``./blog/`` directory.

.. Note::

   If you're using a virtual environment, make sure you've activated
   the virtual environment and are using the ``pyblosxom-cmd`` in the
   ``bin`` directory of your virtual environment!


Deploying
=========

We use the word "deploy" to cover the steps and setup required to turn
your blog into a website.  This could be any of the following:

1. static rendering where your blog is compiled into a set of HTML pages
2. running your blog as a CGI program
3. running your blog as a WSGI application
4. some fourth thing!

The PyBlosxom documentation covers some of these deployment options.

If you're reading this as HTML, then see the Deploy chapters.

If you're reading this on disk, then see the ``deploy*`` files in the
`docs/` directory.

If you want to deploy your blog in a way that's not covered in the
documentation, ask on the *pyblosxom-users* `mailing list`_ or on the
``#pyblosxom`` IRC channel on ``irc.freenode.net``.

.. _mailing list: https://lists.sourceforge.net/lists/listinfo/pyblosxom-users


Post-install
============

After you finish installing PyBlosxom, you should sign up on the
*pyblosxom-users* `mailing list`_.

.. _mailing list: https://lists.sourceforge.net/lists/listinfo/pyblosxom-users

Additionally, please hop on the ``#pyblosxom`` IRC channel on
``irc.freenode.net`` and say hi.  It'll almost certainly help you get
acquainted with PyBlosxom and it'll reduce the amount of time it takes
to get your blog up and going.
