Spice Telephony Install Guide
From SpiceCSM
Please note that the Telephony system is nowhere near complete. Many modules may exhibit strange behavior, or not work at all.
Contents |
System Requirements
Practically any system that can run Erlang can run Spice Telephony. Due to Erlang's concurrent nature, the more cores on the host machine, the better the performance.
Other requirements for a smooth install from scratch are rake, ruby, and GNU make.
An understanding of the erlang shell and runtime is helpful.
FreeSWITCH™
To make the system actually useful, you'll want an install of FreeSWITCH™ available. Please follow the FreeSWITCH™ install guide to install from SVN or 1.0.4 final or better (1.0.4 pre3 isn't recent enough). After you've bootstrapped and run ./configure ; edit your modules.conf and enable event_handlers/mod_erlang_event. Then do a normal install like the install guide details.
We recommend you familiarize yourself with the FreeSWITCH™ basics because Spice Telephony is incomplete and some familiarity with FreeSWITCH™ can help us diagnose any problems you might encounter. At least be familliar with how to use the FreeSWITCH™ console and how to capture debug logs (occasionally a gdb coredump might be helpful if the problem is suspected to lie in mod_erlang_event which we also maintain).
Compiling
In most cases, simply run 'rake'. This will place compiled .beam files in the ebin folder.
Running
The simplest way to start is to use boot.rb. This will create the mnesia schema if needed, create a simple configuration file, as well as provide more succinct start options for the node name, cookie, and configuration file.
boot.rb
To start the node with default options:
./boot.rb
It is equivalent to:
erl -sname testme -setcookie ClueCon -boot ebin/cpx-rel-0.1 -config single
Meaning "Start a node named 'testme' with the cookie of 'ClueCon'. Automatically start the application defined in ebin/cpx-rel-0.1 using the configuration found in single.config."
The mapping from the boot.rb flags to the erl flags are
- -c
- -setcookie
- -s
- -sname
- -n
- -name
- -b
- -boot
- -f
- -config
The boot.rb has 3 additional options:
- --help
- show the start options.
- -d
- use the beam files created after running rake test.
- -r
- adds -run reloader to the erl flags. The reloader will automatically reload a module if it's compiled beam file changes.
The commonly used option are -s, -c, and -f.
./boot.rb -s node_name -c cookie -f config_name
Meaning "Start a node named 'node_name' with the cookie of 'cookie'. Automatically start the application defined in ebin/cpx-rel-0.1 using the configuration found in config_name.config."
.config
If you started with boot.rb, there will be a new file named single.config. It's default contents are:
%% This file was generated by boot.rb.
%% If you are comfortable editing erlang application configuration scripts
%% there is no harm in editing the file.
[{cpx, [
{nodes, ['testme']},
{console_loglevel, info},
{logfiles, [{"full.log", debug}, {"console.log", info}]}
]},
{sasl, [
{errlog_type, error} % disable SASL progress reports
]}].
For each node you intend to run Spice Telephony, the nodes entry must match exactly.
Manual Start
If you choose not to use boot.rb, some steps need to be done manually for a fully functional system.
Create the config file you intend to use (the example above should be sufficient).
Create the mnesia schema and start the application:
$ erl -name node_name -pa ebin -setcookie yourcookie -config config_name 1> mnesia:create_schema([node()]). ok 2> application:start(cpx). ... % some log messages 15:58:09 [NOTICE] <0.2130.0>@cpx:72 Application cpx started sucessfully!
Configuring
The web gui for the applications starts on port 9999 by default. Configuration can be done either by the erl shell as well. See Spice_Telephony_User_Guide for more info.
Configuring FreeSWITCH™ connection
To persistantly configure a FreeSWITCH connection see Spice_Telephony_User_Guide#FreeSWITCH
Somewhere in your FreeSWITCH™ dialplan:
<action application="set" data="queue=MyQueueName"/> <action application="erlang" data="freeswitch_media_manager:! <erlang node>"/>
Now any calls that hit that section of your dialplan will be placed in the provided queue, assuming you've got the system running and that queue is configured.
Outbound Context
To allow the system to originate outbound calls - you'll need to configure an outbound xml dialplan context for FreeSWITCH™:
dialplan/outbound.xml:
<include>
<context name="outbound">
<extension name="outbound_calls">
<condition field="destination_number" expression="^(\d{7}\d*)$">
<action application="set" data="domain_name=$${domain}"/>
<action application="bridge" data="sofia/gateway/mysipprovider.com/$1"/>
</condition>
</extension>
</context>
</include>
Alternately, if you're using openzap, you can send the call out over the PSTN directly:
<action application="bridge" data="openzap/1/A/$1"/>
Run Tests
The easiest way to run the tests is to simply run them from the standard shell.
$ rake test
The above will compile Spice Telephony with the test suite enabled, run the tests, then run the coverage utility. Note that if you do not have eunit avaiable, the compile will fail (eunit is bundled with Erlang as of 12B-5). Additional rake tasks are listed by `rake -T`
See Basic Test Configuration if you want to test drive Spice Telephony and require detailed instructions on setting up a Test Environment.
