Skip to content
kiwiheretic edited this page Dec 11, 2016 · 115 revisions


Welcome to the logos-v2 wiki!

The original purpose of this project was to build a viable alternative to the CancelBot biblebot plugin but without its reliance on XChat. Since then it has become more modular and the bible bot is simply one of its plugins. In fact now it is a useful starting point for any IRC bot project without the steep learning curve of Supybot or Limnoria.

Note that whilst this project also includes the beginnings of a web project that this is completely optional. All configuration can be performed from either the shell command line or from commands issued to the bot from a connected IRC network.

I have now moved development notes to its own page. This is part of my initiative to make the first page of this wiki as relevant as possible to new users. This work is still ongoing.

Command line options (Starting the Bot)

The minimal command line configuration to start the bot would look like the following:

$ python run_bot -s -n Logos --engine-room='#mycontrolroom' 

Here is a summary of the options:

  • -s or --server excepts parameters in the following format. The parameter may simply be a server name like '' Alternatively it is a series of key:value pairs separated by / characters.
    The current keys are: network, port, control, nick, and nickserv. Examples would be "-s". The network key name is optional and may be ommitted. For instance "-s". The only required option is the network name. Also you can specify -s multiple times to connect to multiple IRC servers. However you cannot currently specify different nicks, ie: different -n options, for different IRC servers.)* All parameters on for this argument override the parameters specified by other command line options (eg: -port ). This is really the replacement for all deprecated options listed below.
  • (deprecated) --port <IRC Port> if the bot is connecting to the IRC server on a port other than 6667. (Use the -s option with port instead).
  • (deprecated) -n <IRC Nickname> or --nickname, specify the IRC nickname that the bot should use. (Use the -s option with nickname instead).
  • (deprecated) -p <NickServ Password> or --nick-password, the NickServ password if the bot nick is registered. (Use the -s option with NickServ password instead).
  • (deprecated) --engine-room <#EngineRoom> , the IRC room that to initially connect to. (Use the -s option with 'control' keyword instead).
  • --room-key <Key> , If the Engine Room has an IRC password to join it.
  • --startup-script <path/to/script> , Used to execute a script of IRC commands (in RFC1459 format) when the bot starts up. (You probably don't need this.)
  • --no-services , Prevents authentication with NickServ for networks that don't have it. I might rename this to --no-nickserv in future versions.
  • --monitor-idle-times , Used to allow the bot to monitor idle times of nicks in room by issuing successive /WHOIS commands.

To see all options type the following:

$ python run_bot --help

creating admin user

You should create a bot_admin user using the shell commands_ )

Running the Web Application

TODO: This section is due for a rewrite

To just try out the webserver it is sufficient to run:

$ python runserver

and then point your web browser to your servers ip address and port 8000.

I run the web application on my production webserver using uWSGI. I have a setup (shown below) for running with a proper webserver like nginx or anything with proxy capability. However, I also now have a bash script (in dev branch) which you can run which pretty much does all this anyway.

$ bash_scripts/ /path/to/virtualenv

The virtual environment is the one that was created from the instructions. Running this script will start up the uwsgi webserver and create any needed directories.

For historical reasons my previous setup is as follows:

# Note --http should be used if pointing a browser directly
# to this socket.  Otherwise if upstream from nginx use --socket
source $HOME/venvs/logos-v2/bin/activate
uwsgi --chdir=/home/splat/logos-v2-chatopia \
    --module=logos.wsgi:application \
    --env DJANGO_SETTINGS_MODULE=logos.settings \
    --master --pidfile=/tmp/ \
    --socket= \
    --processes=2 \
    --static-map /static=/home/splat/logos-v2-chatopia/assets \
    --chmod-socket=666 \
    --harakiri=20 \
    --max-requests=5000 \
    --vacuum \
    --daemonize=/home/splat/logs/ # background the process

Replace the parameters map with your path to the logos project on your system with /assets appended to it.

A sample nginx setup for uwsgi is:

upstream logos2 {

# configuration of the server
server {
    # the port your site will be served on
    listen      80;
    # the domain name it will serve for
    server_name; # substitute your machine's IP address or FQDN
    charset     utf-8;

    sendfile on;
    # max upload size
    client_max_body_size 75M;   # adjust to taste
    keepalive_timeout 0;

    # Finally, send all non-media requests to the Django server.
    location / {
        uwsgi_pass logos2;
        include uwsgi_params;

IMPORTANT: Make sure your put any domain names in "allowed_hosts.txt". Failure to do so will cause 502 web browser errors.

Package Dependencies

See the requirements.txt file in the source tree for most up to date information.

How to run tests

$ python test

Known Issues

  • Fails to work properly on Undernet servers if bot nickname is greater than 12 characters. The Undernet server silently truncates the name causing a whole lot of Twisted IRC events to not fire.

  • The bot leaks lots of memory after running for awhile. This happens if DEBUG = True is set in logos/ file. Here is the reason it happens. Change it to False to fix. (AFAIK: I don't this still happens since the bot was upgraded to Django 1.8)

Deployment instructions

To be written .... (really, not that complicated though. The file is currently the best place to start.)

Who do I talk to?

  • Repo owner or admin

kiwiheretic (at) myself (dot) com

Other Pages

You can’t perform that action at this time.