Pierc is an IRC Logbot, paired with a web application for browsing and searching through logs.

It is written in Python (for the logger), and PHP & JavaScript (for the client).


A lot of companies and projects use IRC chat for internal team communication. It's a great way to connect a team semi-synchronously. The only trouble is that an individual team member only has logs of the conversation for when he's around. Clever folks just leave their IRC client logged in all of the time, and log into that whenever necessary — but I'd argue that that's a bit of a pain. Sometimes, teams need a way to archive and search through IRC logs.



Pierc requires that you have the following...

  • A web server, capable of running PHP5 applications, with MySQL installed.
  • A computer with a stable connection to the internet, running Python, with Python-MySQL installed.

1. Cut A Hole In The Database

On your webserver, create a MySQL database for use with Pierc, and a user/password combination that can access the DB.

$ mysql -u adminusername -p
Enter password:
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 5340 to server version: 3.23.54

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

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

mysql> GRANT ALL PRIVILEGES ON pierc.* TO "pierc_user"@"hostname"
    -> IDENTIFIED BY "pierc_password";
Query OK, 0 rows affected (0.00 sec)

Query OK, 0 rows affected (0.01 sec)

mysql> EXIT

If your webserver is not going to be the same computer as the one running the logger, the database will need to be configured to allow remote login.

2. Put Your IRC Bot In That Database

The bot folder in the download contains all of the code necessary to run the log bot. Unpack it into a directory.

Install Python, and the mysql-python libraries. Note that, on Ubuntu (and other Debian based OSes), this requires a simple apt-get install python-mysql.

To configure the bot, copy irc_config.txt.example to irc_config.txt, and mysql_config.txt.example to mysql_config.txt

me@puter: ~/bot/$ cp irc_config.txt.example irc_config.txt
me@puter: ~/bot/$ cp mysql_config.txt.example mysql_config.txt

Set the variables in irc_config to correspond to the channel that you want to log.

If you want to log several channels, use a format like this:

channel: #channel1,#channel2

Set the variables in mysql_config to correspond to the database that you're logging to.

To install the tables in the database, run the command:

me@puter: ~/bot/$ python pierc_db.py

To run the logger, run:

me@puter: ~/bot/$ python pierc.py

Notably, if you're running Pierc on a remote server, you might consider sending output to a file, disabling 'hangup', and nice-ing it.

me@remote: ~/bot/$ nohup nice pierc.py &

3. Make Her Open The Client

The /web/ folder in the download contains all of the code necessary to run the client.

Plunk the directory's contents down in a Apache server, one that's running PHP and PHP-MySQL.

To configure the client, copy config.php.example to config.php

me@puter: ~/web/$ cp config.php.example config.php

Then, set the database details and default channel to mirror the bot's settings.

You should be GOOD TO GO! Try navigating to the client from the web!