INSTALL

.. _install:

======================
 Installing Pyblosxom
======================

Installing Pyblosxom is pretty easy for most situations.  There are
three basic steps to get Pyblosxom running your blog:

1. Installing Pyblosxom

   Installs the Pyblosxom software onto the computer you intend to use
   it on.

   This is covered here.

2. Deploying Pyblosxom

   Sets up your blog on the web server you're going to use.  Since
   there are many ways to deploy Pyblosxom, this is a separate step.

   This is covered in the deployment chapters.

3. Configure your blog to make it your own

   Adjust your ``config.py`` file, install and modify flavours,
   install and configure plugins, ...

   This is covered by the rest of the documentation.


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.github.com/


Upgrading
=========

.. only:: text

   If you're upgrading from a previous version, read through this and
   then read the upgrade instructions in UPGRADE.

.. only:: html

   If you're upgrading from a previous version, read through this and
   then read the upgrade instructions in :ref:`upgrading`.


.. _requirements:

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

Hosting your blog
-----------------

Pyblosxom works with any web server as a CGI application, a WSGI
application, and might work in other contexts.  If you run your blog
in this way, then you'll install Pyblosxom on the web server you plan
to host your blog.

If you can't run CGI/WSGI processes on your web server, then you'll
want to use Pyblosxom to compile your blog into HTML files which you
can host on any web server.  If you run your blog this way, then
you'll install Pyblosxom on a desktop or laptop computer that has your
blog files, you'll compile your blog on that computer, and then push
the resulting HTML files to your web server which will host them.

.. only:: text

   For more information on static rendering, see
   docs/deploy_staticrendering.rst after installing Pyblosxom.

.. only:: html

   For more information on static rendering, see
   :ref:`static-rendering`.


Operating System
----------------

Pyblosxom is well supported on GNU/Linux and Mac OSX.

Pyblosxom is not supported on Windows and may not work well.  If you
decide to run your blog on a Windows server you will be pretty much on
your own as nearly all the documentation and testing is GNU/Linux and
Mac OSX centric.

Having said that, if you run your blog using static rendering, you can
serve the resulting HTML pages on any server you like, Windows
included.


Python
------

Pyblosxom requires at least Python 2.4.  Pyblosxom does not work with
Python 3 or higher---Python 3 is a significant rework of the language.


Installation
============

First step is to install Pyblosxom.  Like all Python programs, there
are a few different ways to install Pyblosxom.  We'll cover two we
think are particularly useful here.

.. Note::

   .. only:: text

      If you're planning to install Pyblosxom to hack on it, then
      check out the install instructions in docs/hacking.rst.

   .. only:: html

      If you're planning to install Pyblosxom to hack on it, then
      check out the install instructions in :ref:`hacking-chapter`.


1. You can install Pyblosxom site-wide which allows all users on the
   computer to use Pyblosxom.

   In order to do this, you must have an administrative account on the
   computer you're installing it on.

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

2. You can install Pyblosxom in a virtual environment using
   `virtualenv`_.

   If you do this, then only you will be able to use Pyblosxom.

   Use this method if any of the following are true:

   1. you don't have administrative access to the computer you're going
      to run Pyblosxom on

   2. you plan to use static rendering to compile your blog into HTML
      files and push those files to the web server

   3. you're just trying out Pyblosxom and you want to install
      Pyblosxom in a way that doesn't affect your computer and is
      easily removed

   See :ref:`Installing in a virtual environment` if this is what you
   want to do.


.. Note::

   If your circumstances change, you can always reinstall Pyblosxom in
   a different way.


.. _Installing site-wide:

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

This walks through installing Pyblosxom site-wide which means it will
be available to all users on the computer you're installing it on.

In order to do this, you must have an administrative account on the
computer you're installing it on.

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. If you have `pip`_ then do::

      sudo pip install pyblosxom

   Or if you 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 in a virtual environment:

Installing in a virtual environment
-----------------------------------

This walks through installing Pyblosxom into a `virtualenv`_ virtual
environment.

If you install Pyblosxom this way, then only you will be able to use
Pyblosxom.

Use this method if any of the following are true:

1. you don't have administrative access to the computer you're going
   to run Pyblosxom on

2. you plan to use static rendering to compile your blog into HTML
   files and push those files to the web server

3. you're just trying out Pyblosxom and you want to install
   Pyblosxom in a way that doesn't affect your computer and is
   easily removed

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 for Pyblosxom in a directory of your
   choosing as denoted by ``<VIRTUAL-ENV-DIR>``::

      virtualenv <VIRTUAL-ENV-DIR>

   This command creates a new directory ``<VIRTUAL-ENV-DIR>`` 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 want to delete Pyblosxom at some point, just delete
   this virtual environment directory and all its contents.

   The virtual environment directory can be anywhere---it doesn't have
   to be in your blog directory and your blog directory doesn't have
   to be inside your virtual environment directory.

   For example, I have a lot of virtual environments set up because I
   fiddle with a lot of Python software.  I have all my virtual
   environment directories under ``/home/willg/venvs``.  I have my
   blog files in ``/home/willkg/blog``.

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.



.. _Creating a blog:

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

.. 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!


To create a blog, do::

   pyblosxom-cmd create <BLOG-DIR>

``<BLOG_DIR>`` can be any directory.  For example::

   pyblosxom-cmd create ./blog/

will generate a directory called ``blog`` in the directory I'm
currently in and put a general blog structure in that directory
including some required files and a first post.


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.

.. only:: text

   See docs/deploy_cgi.rst for deploying your blog as a CGI process.

   See docs/deploy_paste.rst for deploying your blog using
   Paste---this is useful for testing out Pyblosxom on a desktop or a
   laptop to see whether it'd be useful to you).

   See docs/deploy_staticrendering.rst for compiling your blog to HTML
   files that you would then copy to the web server.

   See docs/deploy_apache_mod_wsgi.rst for deploying your blog using
   Apache and mod_wsgi.

.. only:: html

   See :ref:`deploy-cgi-chapter` for deploying your blog as a CGI
   process.

   See :ref:`deploy-paste-chapter` for deploying your blog using
   Paste---this is useful for testing out Pyblosxom on a desktop or a
   laptop to see whether it'd be useful to you).

   See :ref:`static-rendering` for compiling your blog to HTML files
   that you would then copy to the web server.

   See :ref:`deploy-apache-mod-wsgi` for deploying your blog using
   Apache and mod_wsgi.


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``.  You can find
details on the `website <http://pyblosxom.github.com/>`_.


After installing
================

After you finish installing and deploying Pyblosxom, you should look
at plugins and flavours to make your blog your own.

.. only:: text

   See the rest of the files in docs/ for more details.

.. only:: html

   See the rest of :ref:`part-one` for more details.


You should also sign up on the pyblosxom-users mailing list.

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.

Details are on the `website <http://pyblosxom.github.com/>`_.