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.