Installation Manual

Installation Manual

These are the instructions for doing a manual installation, geared towards Linux, tested on Debian, Ubuntu, and CentOS. A kind user has contributed an automated install script for CentOS.

The following instructions assume you setup the webserver to run on port 8086. Any port can be used.

System Requirements

  • Python 2.5 or later
  • Although should work on Windows in theory, testing has only been done on Linux/BSD so far.

Install FreeSWITCH

Checkout and Build

cd /usr/src
svn co freeswitch

NOTE: most recent tested version is 13223

Some tools will be needed for building. If you are on Debian:

apt-get install g++ gcc make autoconf automake libtool

Configure and make, this could take 30 mins or so depending on your machine

./ && ./configure && make


mod_python is required if you want to use the toy voicemail system that ships with WikiPBX or to be able to write IVR's in python.

python-dev package


apt-get install python-dev


yum install python-devel

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

The following are optional but highly recommended. '''The linked modules require extra binaries, see instructions by clicking link'''.

  • mod_python (required for voicemail IVR scripts)

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"/>

as well as the following if you built them in the above step:

<load module="mod_python" global="true"/>

NOTE: global="true" required due to []

Resolved since revision 11560 of FreeSWITCH!?

Rebuild + Install

make install

This will install everything to /usr/local/freeswitch.


The following libraries are required for WikiPBX

Python Libs


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


apt-get install python-xml
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


The State Machine Compiler is needed for the freepy connection library to function.

 tar xvfz smc_5_0_2.tgz
 cd smc_5_0_2/lib/Python
 python install


The webserver is Twisted.web2, and it uses Django as a WSGI plugin which does all of the request processing.

The latest tested version is revision 21361 (twisted subversion repository)


Version 3.3.0-6 or greater is required.


If you are on Debian Etch:

apt-get install python-zopeinterface

If its an older Debian, check the version first

tar.gz (manual installation)

The Zope.interfaces information page is here

cd /usr/src
 tar xvfz zope.interface-3.3.0.tar.gz
 cd zope.interface-3.3.0
 python build
 python install

Twisted Library

cd /usr/src
 svn co --revision 25481 svn:// twisted
 cd twisted
 python install

web2 webserver

Note: This section may be outdated. SVN build 24809 did this successfully on install

Rev. 27230 does install the web2 webserver

By default, at the time of this writing, the twisted setup script does not install the web2 webserver and therefore it must be copied by hand.

cp -R /usr/src/twisted/twisted/web2 /usr/lib/python2.x/site-packages/twisted

You should end up with /usr/lib/python2.X/site-packages/twisted/web2/

Database + Python Adaptor


PostgreSQL 7.4 is recommended over other PostgreSQL versions since all testing has been done with this version. Testing has also been done with MySQL and should work equally well as PostgreSQL. Choose your favorite.

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-7.4 python-psycopg


apt-get install python-mysqldb


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). Anything later may be broken, since Django is still pre-release and undergoing changes.

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

See for more complete instructions.

Text-to-speech Library (needed by voicemail IVR)

The current incarnation of WikiPBX's voicemail system requires either:

  • Cepstral
  • Festival + Sox

It generates the files statically on the command line rather than streaming the audio from freeswitch. So for that reason, to use Cepstral you do not need to install mod_cepstral. However, mod_cepstral can be easily used by making a slight change in change the speak() method to set stream=True for the default value of the
stream flag passed to the method.


Install Cepstral from the instructions on the mod_cepstral page - you don't need mod_cepstral working, just Cepstral itself, but it is recommended to get mod_ceptral working as it will be useful for other things. It is recommended you first test the "swift" command line utility and make sure this works. No need to touch wikipbx/ as Cepstral is already the default


On an Ubuntu system

apt-get install festival festvox-kallpc8k sox

Then edit your file and add/edit

STATIC_TTS_ENGINE = "festival"

That should be all that is needed.

Download/Checkout WikiPBX

Subversion Checkout

cd /usr/src
svn co wikipbx


The following paths will need to be added to the PYTHONPATH environment variable in either /etc/profile or ~/.bash_profile. If the variable does not already exist, it will need to be added.

  • wikipbx - If you extracted to '''/usr/src''', so that you have a '''/usr/src/wikipbx''' directory, then add '''/usr/src''' ('''NOT /usr/src/wikipbx''')
  • freepy add /usr/src/freeswitch/scripts/socket /usr/src/freeswitch/scripts/python to your PYTHONPATH (assuming freeswitch source is installed in /usr/src/freeswitch)


export PYTHONPATH=$PYTHONPATH:/usr/src:/usr/src/freeswitch/scripts/socket

After modifying either /etc/profile or ~/.bash_profile you must 'source' the file to export this to the current environment, for example

source /etc/profile


Copy Template

After checking out from subversion or unextracting the tar.gz, you will have a file called Copy that to and edit it.



Then open and customize the values according to the instructions in the file.

Prepare Database

Create Database User


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


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

Allow DB User to connect


Edit your /etc/postgresql/X.Y/main/pg_hba.conf file to "trust" local connections

# Database administrative login by UNIX sockets
local   all         postgres                          trust


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

Then restart the postgresql daemon


Anything special needed here?

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 wikipbx --user wikipbx wikipbx

If this gives an error, please see postgres: FATAL: Ident authentication failed in the FAQ.


mysqladmin create wikipbx -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)

Initialize Database

Create a database user and a database, and then modify the file accordingly. For the DATABASE_ENGINE setting, postgresql is recommended.

$ cd /usr/src/wikipbx
$ python syncdb

and answer '''no''' when it asks if you want to create a root user.

the output should look like

Creating table auth_message
Creating table wikipbxweb_userprofile

You just installed Django's auth system, which means you don't have any superusers defined.
Would you like to create one now? (yes/no): NO
Installing index for auth.Message model
Loading 'initial_data' fixtures...
No fixtures found.

Server init script

Before the webserver can be started, some configuration needs to be done. This configuration is stored in the database, and there is a utility provided which will ask you a few questions. <font color="red">NOTE:</font> Before proceeding, make sure you log out as the postgres user if you previously did an '''su - postgres''' when creating the database.


It will ask you a few questions.

  • Port - it is recommended to use a high port (eg, 8086) so you can run as a non-priveleged user
  • IP - (default) should work fine here. By default the webserver will bind to all interfaces.

Freeswitch Configuration


Change the file /usr/local/freeswitch/conf/autoload_configs/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.

Startup/Shutdown Scripts

Start WikiPBX web server


NOTE: please ignore any errors such as <tt>freepy.fseventlistener.FreeswitchEventListenerFactory instance at 0x8bb4fcc 2007-10-18 00:34:47+0000 [Uninitialized]clientConnectionFailed!</tt>. This happens because WikiPBX trying to connect to FreeSWITCH (which is not yet running) to listen for certain events, and the connection is failing. The connection will be re-tried in a loop and will succeed once FreeSWITCH is started.

Instructions to start WikiPBX on system startup

Start Freeswitch

/etc/init.d/freeswitch start

Instructions to start FreeSWITCH on system startup


Go to the IP address of the web server, and use the port specified above (8086) in this example. You will see a link under the login section that says '''[Add Root]'''. Please see the User Manual for instructions on how to proceed from here.

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License