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 http://svn.freeswitch.org/svn/freeswitch/trunk 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

./bootstrap.sh && ./configure && make

mod_python

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

'''Debian'''

apt-get install python-dev

'''Fedora'''

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 [http://wiki.freeswitch.org/wiki/Mod_python#ImportError:_.2F...2Fdatetime.so:_undefined_symbol:_PyExc_IOError]

Resolved since revision 11560 of FreeSWITCH!?

Rebuild + Install

make install

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

Dependencies

The following libraries are required for WikiPBX

Python Libs

Pytz

Debian

apt-get install python-tz

Tarball

wget http://pypi.python.org/packages/source/p/pytz/pytz-2008i.tar.gz#md5=15468bcc36c506639b29e55e4b0f52f6
untar ..
python setup.py install

Python-Xml

Debian

apt-get install python-xml

.tar.gz

wget http://ufpr.dl.sourceforge.net/sourceforge/pyxml/PyXML-0.8.4.tar.gz
tar xvfz PyXML-0.8.4.tar.gz
cd PyXML-0.8.4
python setup.py install

log4py

wget http://ufpr.dl.sourceforge.net/sourceforge/log4py/log4py-1.3.tar.gz
tar xvfz log4py-1.3.tar.gz
cd log4py-1.3
python setup.py install

SMC

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

wget http://downloads.sourceforge.net/sourceforge/smc/smc_5_0_2.tgz
 tar xvfz smc_5_0_2.tgz
 cd smc_5_0_2/lib/Python
 python setup.py install

Twisted.web2

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)

Zope.interfaces

Version 3.3.0-6 or greater is required.

Debian

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
 wget http://www.zope.org/Products/ZopeInterface/3.3.0/zope.interface-3.3.0.tar.gz
 tar xvfz zope.interface-3.3.0.tar.gz
 cd zope.interface-3.3.0
 python setup.py build
 python setup.py install

Twisted Library

cd /usr/src
 svn co --revision 25481 svn://svn.twistedmatrix.com/svn/Twisted/trunk twisted
 cd twisted
 python setup.py 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/http.py

Database + Python Adaptor

PostgreSQL

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

MySQL

apt-get install python-mysqldb

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

cd /usr/src
 svn co --revision 5024 http://code.djangoproject.com/svn/django/trunk/ django
 ln -s /usr/src/django/django /usr/lib/python2.x/site-packages

See djangoproject.com 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 baseivr.py: change the speak() method to set stream=True for the default value of the
stream flag passed to the method.

Cepstral

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/settings.py as Cepstral is already the default

Festival

On an Ubuntu system

apt-get install festival festvox-kallpc8k sox

Then edit your settings.py 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 http://svn.wikipbx.org/svn/wikipbx/trunk/ wikipbx

PYTHONPATH

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)

Example:

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

Customize settings.py

Copy Template

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

cp settings_template.py settings.py

Customize

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

Prepare Database

Create Database User

PostgreSQL

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

MySQL

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

Allow DB User to connect

PostgreSQL

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
#

#
# TYPE  DATABASE    USER        CIDR-ADDRESS          METHOD
#

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

Then restart the postgresql daemon

MySQL

Anything special needed here?

Create Database

PostgreSQL

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.

MySQL

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 settings.py file accordingly. For the DATABASE_ENGINE setting, postgresql is recommended.

$ cd /usr/src/wikipbx
$ python manage.py 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.

./initserver.py

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 - 127.0.0.1 (default) should work fine here. By default the webserver will bind to all interfaces.

Freeswitch Configuration

mod_xml_curl

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

<configuration name="xml_curl.conf" description="cURL XML Gateway">
  <bindings>
    <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="http://127.0.0.1:8086/xml_dialplan/" bindings="configuration,dialplan,directory"/>
      <!-- set this to provide authentication credentials to the server -->
      <!--<param name="gateway-credentials" value="muser:mypass"/>-->
    </binding>
  </bindings>
</configuration>

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

./wikipbx.sh

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

Finished

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.