installation manual 0.8

Installation Manual

These are the instructions for doing a manual installation of the new 0.8 release that runs under mod_wsgi, geared towards Linux, tested on Debian, Ubuntu, and CentOS.

If you are migrating from an older version of WikiPBX, see the 0.5 -> 0.8 migration guide

If you are installing on CentOS, see CentOS install notes, which includes a link to a blog page which gives a detailed instructions to install Python2.6.4, mod_wsgi and Django on CentOS 5.4.

System Requirements

  • Python 2.5 or later
  • Linux (known to work on Ubuntu, Debian, CentOS)
  • BSD (people have got it working)

WikiPBX Core

Download/Checkout Code

The code is normally extracted or checked to a wikipbx subdirectory under /usr/src, which this document will assume. In fact you can put it wherever you want.

cd /usr/src

You can get the 0.8.0 release tarball:

tar xvfz wikipbx-0.8.0.tar.gz

Or you can checkout directly from Launchpad.

bzr co lp:~wikipbx-dev/wikipbx/0.8.x wikipbx

Here are the instructions if you need to switch from the zip file to the bazaar branch

Install Code

If you want, you can "install" the code somewhere different than where you downloaded it. However, these instructions just assume you are Extremely Lazy, and just leave it where it already is!

This document will assume the code will be in the wikipbx subdirectory in /usr/src, so you should have a file /usr/src/wikipbx/wikipbx/ (yes, there are two wikipbx directories, that is not a typo)

Settings Template

After installing wikipbx, the first thing you need to do is create a custom that will be edited later.

$ cd /usr/src/wikipbx/wikipbx
$ cp should never be changed! Changes for your specific installation must be done in, NOT

The following settings are needed for CDR's to be correctly posted back to WikiPBX and get written to the filesystem.

  • edit in your preferred text editor
  • modify FREESWITCH_URL_PORT and change the current value to, where MUST be replaced with the domain name you are planning on using.
  • mkdir -p /var/log/wikipbx/cdr/err
  • modify directory specifed in LOG_DIR_ROOT and subdirectory permissions so that the user under which freeswitch process will run has write access to that directory

The remaining settings that must be customized (such as the database settings), will be done later in the installation. Most values in this file can and should be left as the default values. If you're not sure what some of the settings mean, django settings documentation can help.

Get Django

Django provides the O/R mapping layer to the database, and runs as a WSGI in the webserver and handles all the requests.

Django has only been tested up to revision 5024, (in Django source tree). Attempting to run with later versions of Django won't work. (currently in progress, see roadmap)

If you're using Ubuntu or other Debian-based distro, you may need to work around an issue related to python's site-packages directory.

Assuming you are using python 2.5, your commands would be:

 cd /usr/src
 svn co --revision 5024 django
 ln -s /usr/src/django/django /usr/lib/python2.5/site-packages

NOTE: replace 2.5 with your version of python! Verify this was done correctly by starting a python shell and typing:

import django
print django.__file__

You should not get an error and see the path to your django installation in your system directory.

See for more complete instructions of installing django.

Install mod_wsgi

Mod_wsgi is the "container" which WikiPBX will use to interface with the webserver.

Since this is a large step, it has been factored out into a separate page. This is an important step that cannot be skipped.

Continue on to install mod_wgi instructions and then come back here.

Configure Apache2 mod_wsgi

Apache2 must be configured to route requests to WikiPBX, via mod_wsgi.

Since this is a large step, it has been factored out into a separate page. This is an important step that cannot be skipped.

Continue on to configure mod_wgi instructions and then come back here.

WikiPBX Dependencies

The following libraries are required for WikiPBX

Python Libs


Pytz has some date/timezone functions

apt-get install python-tz
untar ..
python install


Debian / Ubuntu Gutsy
apt-get install python-xml

NOTE Ubuntu Hardy and later users: Do not use the python-xml package, it is effectively broken, instead use the .tar.gz installation method. If you use the python-xml package you will get "no module named ext" when trying to load the home page.

tar xvfz PyXML-0.8.4.tar.gz
cd PyXML-0.8.4
python install


tar xvfz log4py-1.3.tar.gz
cd log4py-1.3
python install

Database + Python Adaptor


Tested on PostgreSQL 7.x and 8.x

In addition to the database, you will need the psycopg (version 1) adaptor layer. psycopg2 will probably work too, but has not been tested.

 apt-get install postgresql-x.x python-psycopg


 apt-get install mysql-server python-mysqldb

Prepare Database

Create Database User


$ su - postgres
$ createuser --pwprompt --encrypted --no-adduser wikipbxuser

When it asks you if the new user can create databases, answer YES. The other questions can be answered with NO.


$ mysql mysql --user root -p
$ mysql> GRANT ALL PRIVILEGES ON wikipbx.* TO wikipbxuser@localhost IDENTIFIED BY 'MYPASSWORD';

Allow DB User to connect


The default postgresql configuration requires that the connection be from the same UNIX user as the db user for local connections. If you don't want to create a UNIX user called wikipbxuser (or whatever you choose), then you will probably have to modify the postgresql configuration.

If that is the case, then edit your /etc/postgresql/X.Y/main/pg_hba.conf file to use md5 password authentication for local connections

# Database administrative login by UNIX sockets
local   all         postgres                          md5


# "local" is for Unix domain socket connections only
local   all         all                               md5
# IPv4 local connections:
host    all         all          md5
# IPv6 local connections:
host    all         all         ::1/128               md5

Then restart the postgresql daemon

Create Database


Assuming you already have a database user named wikipbx, issue the following to create a database named wikipbx. When it prompts you for the password, enter the password you entered above when creating the wikipbx database user.

 createdb --password --owner wikipbxuser --user wikipbxuser wikipbx

If this gives an error, please see this entry in the FAQ


 mysqladmin create wikipbx -u wikipbxuser -p

NOTE: since WikiPBX uses database transactions in a few places, to be on the safe side you should create the database so that it has transactional support. (TODO: add instructions on how to do this)

Update Settings

After a database user and database have been created, update the file to reflect these values. If you don't do this, the next step will fail.

Initialize Database

$ cd /usr/src/wikipbx
$ python syncdb --noinput

the output should look like

Creating table auth_message
Creating table django_content_type
Installing index for wikipbxweb.UserProfile model
Installing index for auth.Message model


If you don't already have FreeSWITCH installed, you will need to install it. Please see the FreeSWITCH installation guide for installing FreeSWITCH.

The latest version of FreeSWITCH that has been tested is 15699 which was released on (28 Nov 2009). Later versions of FreeSWITCH should work without any problem. As far as earlier versions tested, FreeSWITCH 13501 is known to work fine. Earlier versions will most likely also work.

Enable Modules - Compile Time

Modules are enabled by editing the modules.conf file and uncommenting or adding the appropriate lines. modules.conf appears in the root of the FreeSWITCH source tree (eg, /usr/src/freeswitch), but only '''after''' 'configure' has been run.

The following '''modules''' must be built and enabled:

  • mod_event_socket
  • mod_xml_curl
  • mod_xml_cdr

Rebuild + Install

After the modules.conf file has been changed, freeswitch must be rebuilt:

 make install

Enable Modules - Run Time

Open the file /usr/local/freeswitch/conf/autoload_configs/modules.conf.xml

Uncomment all the following modules:

<load module="mod_event_socket"/>  
<load module="mod_xml_curl"/>
<load module="mod_xml_cdr"/>

Configure mod_xml_curl

Change the file /usr/local/freeswitch/conf/xml_curl.conf.xml

<configuration name="xml_curl.conf" description="cURL XML Gateway">
    <binding name="example">
      <!-- The url to a gateway cgi that can generate xml similar to
           what's in this file only on-the-fly (leave it commented if you dont
           need it) -->
      <!-- one or more |-delim of configuration|directory|dialplan -->
      <param name="gateway-url" value="" bindings="configuration,dialplan,directory"/>
      <!-- set this to provide authentication credentials to the server -->
      <!--<param name="gateway-credentials" value="muser:mypass"/>-->

You will also need to make sure that mod_xml_curl was enabled in modules.conf before compiling FreeSWITCH, and that it is enabled for runtime loading in modules.conf.xml. See mod_xml_curl for detailed instructions.

Build ESL with Python Bindings

ESL is the socket library used from the Web Server code to communicate with freeswitch

Change directory to libs/esl directory under freeswitch source tree

NOTE: If you are running an older version of FreeSWITCH, you will first need to manually edit python/Makefile to use the version of python you prefer to use. When you open that file it should be clear how to modify it, it's a small file.

$ make pymod

Start Services

Start Apache2

WikiPBX must be started before FreeSWITCH, so that FreeSWITCH can pull the configuration from WikiPBX.

$ /etc/init.d/apache2 restart

To view logs:

$ tail -f /var/log/apache2/error.log /var/log/apache2/

Start Freeswitch

$ cd /usr/loca/freeswitch/bin
$ ./freeswitch

Verify Installation

Home Page

Navigate to

You should see a link under the login section that says '''[Add Root]'''.

FreeSWITCH configuration

  • Type "sofia status" on the freeswitch console
  • Verify that you see the sip profile(s) you created in WikiPBX listed, and no others.

FreeSWITCH connectivity

  • Create a root user
  • Create an account and initial account admin
  • Login as the account admin
  • Click "Live Calls" link on the left toolbar — you should not see any errors
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License