Installation — Ibid v0.1.1 documentation

### Navigation

- index
- modules |
- next |
- previous |
- Ibid v0.1.1 documentation »

# Installation

The preferred method of installing a production Ibid is to use the packages provided by your distro. Ibid is available in Debian (since squeeze) and Ubuntu (since Lucid). Additionally, private backport repositories are available for supported stable releases of:

- Debian (lenny)
- Ubuntu (hardy-karmic)

Installing Ibid through your distribution’s package-management system should give you the least hassles in the long run [1].

For plugin-development this will be sufficient, but for interaction with the Ibid development community (i.e. contributing code) or drastic internal changes, you will probably want to work from source instead.

## Prerequisites

### Python

You’ll need a sane Python environment and a few Python 3rd-party packages, described below.

We attempt to support all Python 2.x releases >= 2.4. However, we’d recommend the most recent stable 2.x release, as Python memory usage has improved and more recent Python releases have been better tested with Ibid. (We have to go out of our way to test with 2.4...) Python 3.x support is off the cards until our dependencies are 3.x capable.

We expect Ibid to work on most operating systems that can provide Python, but only develop and test heavily on Debian and Ubuntu Linux.

### Python Libraries:

- Twisted framework (core sources)
- Twisted Words (IRC, XMPP)
- Wokkel. (XMPP)
- SQLAlchemy 0.5 preferred, 0.4 compatible.
- ConfigObj >= 4.7.0
- python-dateutil
- SOAPpy [3]
- Setuptools

Many core plugins require the following Web scraping & parsing libraries:

- ElementTree (only needed for Python 2.4)
- html5lib
- BeautifulSoup
- SimpleJSON (only needed for Python < 2.6)

Web source and web services:

- Jinja

Other sources:

- SILC: pysilc

There are many non-essential plugins that require other libraries or programs, they are described in the plugin documentation.

### Database

Ibid needs a relational database [2]. MySQL, PostgreSQL, and SQLite are all supported as first-class citizens. Using the database-independent backup & restore tool, it is straightforward to migrate between database engines at any time.

## Database Creation

By default Ibid will use SQLite, which is a perfectly capable database, but if you have a MySQL or PostgreSQL server handy, you may prefer to use it to save some memory or take advantage of the more powerful feature-set.

If you are using SQLite, you can skip over this section, but for MySQL or PostgreSQL, you’ll need to create a database and DB user before running `ibid-setup`.

### MySQL

Install MySQL. On Debian/Ubuntu:

    user@box $ sudo aptitude install mysql-server python-mysqldb

You’ll be prompted to set a root password for your server. You should probably do that.

Create a database for your bot:

    user@box $ mysql -u root -p
    Enter password:
    Welcome to the MySQL monitor.
    mysql> CREATE DATABASE joebot CHARSET utf8;
    Query OK, 1 row affected (0.02 sec)

    mysql> GRANT ALL PRIVILEGES ON joebot.* TO joebot@localhost IDENTIFIED BY 'mysecret';
    Query OK, 0 rows affected (0.13 sec)

    mysql> quit
    Bye

In this example, the database is called `joebot`, the user `joebot` and the password is `mysecret`, so the DB URL will be:

    mysql://joebot:mysecret@localhost/joebot

### PostgreSQL

Install PostgreSQL. You’ll also need the `citext` contributed module. On Debian/Ubuntu:

    user@box $ sudo aptitude install postgresql postgresql-contrib python-psycopg2

Create a database for your bot:

    user@box $ sudo -u postgres -i
    postgres@box $ createuser -D -R -S -P joebot
    Enter password for new role:
    Enter it again:
    postgres@box $ createdb -O joebot joebot
    postgres@box $ psql -f /usr/share/postgresql/8.4/contrib/citext.sql joebot
    postgres@box $ logout

In this example, the database is called `joebot` and the user `joebot` if the password were `mysecret`, the DB URL would be:

    postgres://joebot:mysecret@localhost/joebot

## Package Managed Installation

### Add the APT source

These repositories are only necessary if you are using an old Debian / Ubuntu release that doesn’t include Ibid.

Debian (lenny):
  `deb http://ibid.omnia.za.net/debian/ lenny-backports main`
  GPG Key: 0x5EB879CE
Ubuntu (pre-lucid):
  `deb http://ppa.launchpad.net/ibid-core/ppa/ubuntu karmic main`
  If you are using a different release to `karmic`, substitute its name.
  GPG Key: 0xFD1C44BA

You can follow these instructions or add it from a terminal like this:

    user@box $ echo deb http://ppa.launchpad.net/ibid-core/ppa/ubuntu `lsb_release -cs` main | sudo tee /etc/apt/sources.list.d/ibid.list
    user@box $ sudo apt-key adv --recv-keys --keyserver keyserver.ubuntu.com 0xFD1C44BA
    user@box $ sudo aptitude update

### Install Ibid

    user@box $ sudo aptitude install ibid

Now you should probably create a user for your bot to run as. While every effort is made to ensure that your bot won’t do naughty things, we can’t guarantee that there is no way to exploit it. If you are feeling adventurous, skip down to creating a bot directory:

    user@box $ sudo adduser --disabled-login ibid

Switch to the bot user:

    user@box $ sudo -u ibid -i
    ibid@box $

If you are going to be using MySQL or PostgreSQL set up your database now.

Then you’ll need to create a directory for your bot to live in:

    ibid@box $ mkdir botdir
    ibid@box $ cd botdir

Now you can install the bot:

    ibid@box $ ibid-setup
    Couldn't load core plugin: botname
    Couldn't load knab plugin: No module named perl
    Couldn't load trac plugin: argument of type 'NoneType' is not iterable
    What would you like to call your bot? joebot
    Please enter the full URL of the database to use, or just press Enter for an SQLite database.
    Database URL:
    Please enter the details for the primary source. Press Enter for the default option.
    Source name (e.g. freenode, atrum, jabber): freenode
    Server: irc.freenode.net
    Port:
    Source type (irc or jabber): irc
    Default channels to join (comma separated): #myawesomechannel
    Nick/JID: joeuser
    Password: [my password]
    Account created with admin permissions

Note

This will throw out some harmless errors (about plugins that you don’t have pre-requisites for).

Load any factpacks you desire (in this case, common greetings):

    ibid@box $ ibid-factpack greetings.json

Now would be the time to configure your bot. But for now, let’s just get it running:

    ibid@box $ twistd -n ibid

You should see copious debugging output, and the bot should log into your IRC channel.

## Installation From Source

If you want to do any development, or install from trunk or a specific branch, you’ll need Bazaar installed.

Firstly, you need the dependencies listed above. We recommend a recent release of Debian/Ubuntu Linux, and the instructions are tailored for such. If you use something else, you’ll have to interpolate.

Install the required python modules. You can use another DB, but we default to SQLite. If you are not using Debian/Ubuntu or would prefer to have these dependencies installed in a virtualenv, you can skip this step:

    user@box $ sudo aptitude install bzr python-configobj python-sqlalchemy \
      python-twisted python-beautifulsoup python-celementtree \
      python-html5lib python-setuptools python-simplejson \
      python-soappy python-jinja python-dateutil python-virtualenv

Create a user to run your bot as:

    user@box $ sudo adduser --disabled-login ibid

Create a virtualenv to install Ibid to:

    user@box $ virtualenv ve

Note

This isn’t strictly necessary as Ibid can run out of a source checkout for development. But for long-term deployments it is sensible to separate the source from the botdir.

Checkout the latest version of Ibid (instead of this, you could extract a source tarball):

    user@box $ sudo -u ibid -i
    ibid@box $ bzr branch lp:ibid
    ibid@box $ cd ibid

Install Ibid:

    user@box $ . ~/ve/bin/activate
    user@box $ ./setup.py install --no-dependencies

Note

If you didn’t install the packages listed in the first step, you’ll have to remove `--no-dependencies` so setuptools can do its magic.

If you are going to be using MySQL or PostgreSQL set up your database now.

Then you’ll need to create a directory for your bot to live in:

    ibid@box $ mkdir ~/botdir
    ibid@box $ cd ~/botdir

Set up your bot:

    ibid@box $ ibid-setup

Note

This will throw out some harmless errors (about plugins that you don’t have pre-requisites for).

If you haven’t created a configuration file, it will ask you to give the bot a name, and describe the first source. A source is an IRC network, jabber, or SILC network.

It’ll ask you to enter the details of the first administrative account. Assuming you will be connecting the bot to an IRC server, enter your nick, the network’s name, and a password (e.g. “joebloggs”, “freenode”, “s3cr3tpass”).

Load any factpacks you desire (in this case, common greetings):

    ibid@box $ ibid-factpack ~/ibid/factpack/greetings.json

Runi your bot:

    ibid@box $ twistd -n ibid

Footnotes

[1] | Your distribution of choice not listed here? That’s probably because none of the current Ibid developers use it. Why not chip in and help us package Ibid for you.

[2] | If you don’t need user-accounts (and many other features), the database code could be removed. It’d probably be quite a bit of work, though.

[3] | SOAPpy can be hard to install, so we have debian packages and eggs to help. `setup.py` knows where to look.

### Navigation

- index
- modules |
- next |
- previous |
- Ibid v0.1.1 documentation »