===================
Installing Gozerbot
===================

This document will get you up and running with Gozerbot.


1) Install Python
~~~~~~~~~~~~~~~~~

Being a Python bot, Gozerbot requires Python_ to run. Gozerbot will work
properly with any Python version 2.4 and higher.

You can obtain Python from:
1.  Python_
2.  Debian_: apt-get install python
3.  FreeBSD_: cd /usr/ports/lang/python ; make
3.  ArchLinux_: pacman -S python

.. _`Python`: http://www.python.org/
.. _`Debian`: http://www.debian.org/
.. _`FreeBSD`: http://www.freebsd.org/
.. _`ArchLinux`: http://www.archlinux.org/


2) Get your database running
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you plan to use Gozerbot with a MySQL_ database backend, you need to 
setup a database for Gozerbot first. Connect to your database as root,
and setup the proper privlieges:
::

    mysql> CREATE DATABASE gozerbot;
    Query OK, 1 row affected (0.00 sec)

    mysql> GRANT ALL ON gozerbot.* TO 'gozerbot'@'localhost' 
        -> IDENTIFIED BY 's3cr3t';
    Query OK, 0 rows affected (0.00 sec)

    mysql> FLUSH PRIVILEGES;
    Query OK, 0 rows affected (0.00 sec)

.. _`MySQL`: http://www.mysql.org/


3) Getting the gozerbot code
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

There are several ways of installing Gozerbot. Some distributions may have
Gozerbot packaged which we will not cover in this document. Refer to the
documentation of your package manager on how to obtain Gozerbot in your
distribution.

For all other distributions or operating systems, you can get Gozerbot in a
few different flavours.

Getting a stable version (tarball)
----------------------------------

You can download a stable tarball version from our `main site`_. The download
file will be named gozerbot-0.x.y.z.tar.gz, where:

    x.  major version
    y.  minor version
    z.  patch level (bugfix releases)

Once your have downloaded the tarball successfully, extract the tarball:

    $ gunzip -c gozerbot-0.x.y.z.tar.gz | tar -xvf -
    gozerbot-0.x.y.z/
    ....
    $

.. _`main site`: http://www.gozerbot.org/

Getting a beta or preview version (hg)
--------------------------------------

You can download a beta or preview version using Mercurial_. The advantage 
of running beta code is, that you can UPGRADE ON THE FLY, using the !upgrade 
command. To download the current version, use:

    $ hg clone http://www.gozerbot.org/hg/gozerdev/
    destination directory: gozerdev
    requesting all changes
    adding changesets
    adding manifests
    adding file changes
    added 1840 changesets with 3824 changes to 459 files
    308 files updated, 0 files merged, 0 files removed, 0 files unresolved
    $

.. _Mercurial: http://www.selenic.com/mercurial/

4) Installing the Gozerbot code
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Once you have downloaded the code, you can install the code site-wide, if you
for example prefer to run multiple Gozerbot instances.

Local installation
------------------

You can perform a local installation using:

    $ cd gozerbot/  # or gozerbot-0.x.y.z
    $ python setup.py install --prefix /home/users/joe
    ...

Global installation
-------------------

You can perform a global installation using:

    $ cd gozerbot/  # or gozerbot-0.x.y.z
    $ python setup.py build
    $ sudo python setup.py install
    ...

5) Setting up gozerbot
~~~~~~~~~~~~~~~~~~~~~~

Change to the working directory you wish to run Gozerbot from. If you don't 
have a working directory yet, create one.

    $ mkdir mybot
    $ cd mybot/

Now you can call ``gozerinit`` to setup your bot. If you did not do a local
or global installation, running the bot from the directory you downloaded
Gozerbot in, use ``bin/gozerinit``

    $ gozerinit
    $ ls
    gozerdata
    $

6) Configuring Gozerbot
~~~~~~~~~~~~~~~~~~~~~~~

You're almost done now! The last thing you will have to do, is editing the
``gozerdata/config`` file. The most important settings are:

    ==================== ======================================================
    Flag                 Description
    ==================== ======================================================
    ``owneruserhost``    This is your exact hostmask, in the form:
                         ident@hostname.tld
                         The bot uses this to identify you as owner on IRC.

    ``nick``             The nickname of your Gozerbot.

    ``server``           The server your Gozerbot will connect to.
    ==================== ======================================================

If you wish to use MySQL_ as your database backend, you will also have to 
configure:


    ==================== ======================================================
    Flag                 Description
    ==================== ======================================================
    ``dbenable``         Set this to ``1`` if you want to enable the database.

    ``dbtype``           Currently only MySQL_ is considered stable, you can use
                         this by entering ``mysql`` here.

    ``dbhost``           The host of your database, use ``localhost`` to connect
                         to your database using the default UNIX socket.

    ``dbuser``           The username that is allowed to connect to the database.

    ``dbpasswd``         The password used for connecting to the database.

    ``dbname``           The name of the database you are going to use.

    ``dboldstyle``       Set to ``True`` if your MySQL_ version is older than 4.1
    ==================== ======================================================

.. _`MySQL`: http://www.mysql.org/

6) Running Gozerbot
~~~~~~~~~~~~~~~~~~~

All you have to do, is starting the bot with the ``gozerbot`` command. If
you did not do a local or global installation, running the bot from the directory 
you downloaded Gozerbot in, use ``./runbot``.

7) Logging Gozerbot to a file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can run Gozerbot in the background, logging to a file, by using:

    $ gozerbot 2>&1 > gozerbot.org & disown

Alternately, you can run Gozerbot in a screen_:

    $ screen gozerbot

.. _`screen`: http://www.gnu.org/software/screen/
