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. See also wsgi migration guide

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

Please see the FreeSWITCH installation guide for installing FreeSWITCH. The latest version of FreeSWITCH that has been tested with WikiPBX is 13501

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

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]

Rebuild + Install

 make install

WikiPBX Dependencies

The following libraries are required for WikiPBX

Python Libs

ESL

Build ESL with Python Bindings

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

• Go to libs/esl directory under freeswitch source tree
• Edit python/Makefile to use the version of python you prefer to use
• Run <tt>make pymod</tt>

eventsocket

eventsocket is the twisted-based socket library used from the twisted process that listens for events from freeswitch and updates the database.

To install eventsocket:

• cd /usr/lib/python2.5/site-packages/
• wget http://eventsocket.googlecode.com/files/eventsocket.py

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

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

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 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. Here is an [[examples settings.py]].

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|this entry 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

Change the file /usr/local/freeswitch/conf/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://wikipbx.yourserver.com/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 twisted plugin

You will need to make sure you have the following two directories in your PYTHONPATH (assuming you checked out to /usr/src/wikipbx):

• /usr/src/wikipbx/
• /usr/src/wikipbx/wikipbx

$ twistd -n wikipbx

The part of wikipbx that uses twisted is using twisted plugin architecture, so we're using twistd program rather than our own script. It supports a lot of features concerning like logging, daemonizing and many more, to see them have a look at man twistdor run:

twistd -h

The "-n" flag is added to turn off process daemonization, you may want to omit it in production.

Our plugin supports some addition configuration options, to see them run:

twistd wikipbx -h

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 [[Main_Page#User_Manual|User Manual]] for instructions on how to proceed from here.