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

You can get the 0.8.0 release tarball:

wget http://www.wikipbx.org/releases/wikipbx-0.8.0.tar.gz

Or preferably checkout directly from Subversion. If you are going to put this in production, checkout from the 0.8 release branch:

svn co http://svn.wikipbx.org/svn/wikipbx/branches/releases/0.8.0 wikipbx

Or if you have to be on the bleeding edge, you can try the trunk (no stability guarantees however):

svn co http://svn.wikipbx.org/svn/wikipbx/trunk/ wikipbx

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

Settings Template

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

$ cd /usr/src/wikipbx/wikipbx
$ cp settings_template.py settings.py

settings_template.py should never be changed! Changes for your specific installation must be done in settings.py, NOT settings_template.py

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

• edit settings.py in your preferred text editor
• modify FREESWITCH_URL_PORT and change the current value to http://wikipbx.yourserver.net, where yourserver.net 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 http://code.djangoproject.com/svn/django/trunk/ 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__

See djangoproject.com 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

Pytz has some date/timezone functions

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

Database + Python Adaptor

PostgreSQL

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

MySQL

 apt-get install mysql-server python-mysqldb

Prepare Database

Create Database User

PostgreSQL

$ 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 mysql --user root -p
$ mysql> GRANT ALL PRIVILEGES ON wikipbx.* TO wikipbxuser@localhost IDENTIFIED BY 'MYPASSWORD';

Allow DB User to connect

PostgreSQL

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
#

#
# TYPE  DATABASE    USER        CIDR-ADDRESS          METHOD
#

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

Then restart the postgresql daemon

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

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

MySQL

 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 settings.py file to reflect these values. If you don't do this, the next step will fail.

Initialize Database

$ 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.

FreeSWITCH

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

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/wikipbx.yourserver.net-error.log

Start Freeswitch

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

Verify Installation

Home Page

Navigate to http://wikipbx.yourserver.net

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