Skip to Content

Installation Guide

  1. Requirements
    1. Hardware
      1. Enterprise
      2. Compact
    2. DNS
    3. Other things
    4. Firewall considerations
  2. Emerginov Enterprise
  3. Emerginov Compact
  4. Post installation testing
    1. Web tests
      1. Admin
      2. Project management
      3. First PHP
      4. Database access
    2. Vocal tests
      1. Incoming call
      2. Outgoing call
      3. PSTN/PLMN management
    3. SMS tests
      1. SMS sending
      2. SMS reception
    4. Mails tests
      1. Sending mails
      2. Receiving mails

There are 2 versions of Emerginov: Compact and Enterprise. The compact version can be installed on a single machine. The Enterprise version is scalable but is based on a virtualized environment.

Requirements

Hardware

Enterprise

If you plan to setup an Enterprise version:

  • 4 machines (routing, gardien, content, dev) with:
    • Ubuntu 12.04 LTS server up to date (fresh installation with SSH only, do not install MySQL or Apache)
    • 512Mo of RAM minimum (recommanded: 2Go)
    • 2 vCPU
    • 20 Go of storage (50Go recommanded)
    • 1 ethernet interface with a private IP address
    • FOR ROUTING ONLY: 1 ethernet interface with a public IP address (protected with a firewall, see below)
  • A Gateway machine. See Gateway page for more info
  • If you want to backup VM, plan to have 100Go of storage minimum.

Example of network planning:

  • Subnet is 192.168.0.0/24
  • Public IP address is 2.3.4.5
Nodeeth0eth1
routing (VM)192.168.0.22.3.4.5
gardien (VM)192.168.0.3n.a.
content (VM)192.168.0.4n.a.
dev (VM)192.168.0.5n.a.
gateway (physical machine)192.168.0.6n.a.

Compact

If you plan to setup an Compact version:

  • 1 machine (the compact node) with
    • Ubuntu 12.04 LTS server (fresh installation with SSH only, do not install MySQL or Apache)
    • 1Go of RAM minimum
    • 1 ethernet interface with a public IP address (protected with a firewall, see below)

DNS

For both compact and enterprise version of Emerginov, you'll need an domain name properly configured in a domain name server with these records:

@                       3600  A          public_ip_address
@                       3600  MX         10 mail
www                     3600  CNAME      @.
mail                    300   A          public_ip_address
api                     300   CNAME      @.
phpmyadmin              3600  CNAME      @.
svn                     3600  CNAME      @.
projects                3600  CNAME      @.
_sip                    3600  SRV        0 0 5060 public_ip_address
_sip._udp               3600  SRV        0 0 5060 public_ip_address

Lets imagine you bought emerginov.fr from a Domain Name provider (such as NordNet or BookMyName) and your public IP address is 2.3.4.5, you should configure the DNS with:

@                       3600  A          2.3.4.5
@                       3600  MX         10 mail
www                     3600  CNAME      @.
mail                    300   A          2.3.4.5
api                     300   CNAME      @.
phpmyadmin              3600  CNAME      @.
svn                     3600  CNAME      @.
projects                3600  CNAME      @.
_sip                    3600  SRV        0 0 5060 2.3.4.5
_sip._udp               3600  SRV        0 0 5060 2.3.4.5

Other things

  • 1 mail account (GMail tested, any SMTP server should work)
  • 1 Google Analytics account (optional)

Firewall considerations

In front of your public IP address, you should have a firewall that will only accepts those flows:

From Internet to Emerginov (routing node in case of a enterprise installation, compact node in case of compact installation):

  • HTTP/HTTPS (Dest port: TCP-80/443)
  • SIP (Dest port: UDP-5060)
  • RTP (Dest port: UDP-20000-20999)

From Emerginov To Internet:

  • HTTP/HTTPS (Dest port: TCP-80/443) is required

Please, apply thoses rules as they are very important for the security of your installation.

You may also need some other rules for the gateway. Please read the Gateway page carefully as well.

Emerginov Enterprise

This is the default version of Emerginov. It is based on, at least, 5 machines : 

  • gardien
  • routing
  • dev
  • content
  • gateway

Of course, every machine can be a Virtual Machine (Proxmox is a very good and quite easy to use Virtual Machine Server if you plan to setup one)

The installation procedure is detailed here:  Installation Guide Emerginov Enterprise

Most of the time, you will also need a gateway with an enterprise Emerginov installation.
The installation procedure for the gateway is detailed here: Installation Guide Emerginov Gateway

Please be sure pre-requirements are OK before starting...

Emerginov Compact

This is exactly the same installation as Enterprise but with only 1 machine (virtualized or not).
This kind of installation can be used to test an Emerginov installation.
The gateway is included in this compact installation but have some limitation (you won't be able to use a Digium T2 card).

The installation procedure is detailed here: Installation Guide Emerginov Compact

but please read this whole page before proceeding.

Post installation testing

Once your installation is successful, you may perform a suite of tests to be sure that the different features are working fine.

Web tests

Admin

  • Go on the main portal => http://www.<your domain>
  • Connect as <admin> on the admin portal (creds in the emerginov.pp, by default admin/admin2345) => http://www.<your domain>/admin/, accept certificates
  • Click on Users menu (left menu), create an user <user> as administrator
  • Browse the different <admin> links (Todo list, Projects, Users, VoIP, Project API, PHPMyAdmin, Appliance Manager)

Project management

  • Log out as <admin> and log in as user <user> on your selfcare https://<domain>/main_authen/selfcare.php
  • Create a project <project> by clicking on Create a new project (check the MySQL database option)
  • Click on go back => the project shall be displayed as inactive (in grey)
  • Log out (as <user>) and log in as admin on the admin page => the project should be displayed in the Todo list (default page at login)
  • Validate the project <project>
  • Log out (as <admin>) and log in as user <user> => <project> should be displayed as active (tools logo in blue)
  • Log out (as <user>) and go to the pre registration page http://www.<yout domain/pre_register.php, complete the form with a <new user>
  • Log as <admin> and validate the pre_registered <new user>.
  • Log out (as <admin>) and log in as user <new user>
  • Log out (as <new user> and log in as <admin>
  • delete <new user>
  • Log out (as <admin>) and try to log in as new user (shall not be possible)

First PHP

  • If not
  • Create a page index.php in <project> through the SVN editor https://svn.<your domain>/listing.php?repname=<project> in trunk/web (trust certificates)
  • reload and edit the page, copy/paste the following code
<?php
echo "Hello";
?>
  • Save the index.php page (CTRL+S)
  • Go on http://projects.<your domain>/<project>/ => the page shall be displayed
  • Edit, replace <echo "Hello"> by <echo "Hello World">
  • Save the index.php page
  • Check that the page has been modified at http://projects.<your domain>/<project>/

Database access

  • Check that the database is available at http://phpmyadmin.<your domain>/dev/
  • Select the database that correspond to your project (it should be named like: proj_<project>_<random char>)
  • Create a new table and insert some values in it with the following code:
CREATE TABLE IF NOT EXISTS `members` (
 `login` text NOT NULL
);

INSERT INTO `members`(`login`) VALUES ('arnaud');
INSERT INTO `members`(`login`) VALUES ('morgan');
  • Through websvn, create a new PHP file called mysqltest.php, and copy/paste the following code:
<?php
// Load required passwords
require_once("passwords.php");

// Connect on MySQL with Php Database Object
$connection = new PDO("mysql:host=$mysql_db_server;dbname=$mysql_db_name", $mysql_db_login, $mysql_db_password);

// Prepare a SELECT query
$select = $connection->query("SELECT * FROM members");

// Fetch all results as an array
$results = $select->fetchAll(PDO::FETCH_COLUMN);

// Print results
print_r($results);

?>
  • Check that the MySQL connection is working at http://projects.<your domain>/<project>/mysqltest.php

Vocal tests

Incoming call

  • Log in as user <user> on your selfcare https://<domain>/main_authen/selfcare.php
  • Edit, modify and save the incoming.php file. The default file should be like this one:
<?php
/*
 * This file has automacally been created by Emerginov Project Creation mecanism.
 * The purpose of this file is to provide a sample incoming voice call management.
 * Please edit the file to handle properly your incoming voice calls.
 * You might find many information on how to do so on Emerginov wiki.
 * http://emerginov.ow2.org/xwiki
 */

// Load required configuration & Emerginov Class
require_once("passwords.php");
require_once("Emerginov.php");

// Answer the call
$call->Answer();

// Wait 2 sec;
sleep(2);

// Play echo test
$call->Play("echo_test");

// Record user
$call->Record("record");

// Playback what the user said
$call->Play("record");

// Wait 2 sec;
sleep(2);

// Hangup the call
$call->Hangup();
?>
  • From a VoIP client (configured on <your domain>, see How to configure a VoIP client), call your service at sip:<PROJECTNAME UPPERCASE>@<your domain> => the echo test should work as expected.

Outgoing call

  • Log in as user <user> on your selfcare https://<domain>/main_authen/selfcare.php
  • Click on your <project>
  • Click on the API shop tab
  • Select Outgoing Call
  • Put your quota then click on OK
  • Click on Save the modifications
  • Log out as <user> then connect as <admin> on the admin portal => http://www.<your domain>/admin
  • Click on Projects API
  • Select <project>
  • Click on Accept subscription
  • Click on Save last settings
  • Log out as admin and log in as user <user> on your selfcare https://<domain>/main_authen/selfcare.php
  • Click on your <project>
  • Create, modify and save the makecall.php of <your project> (with websvn) with the following code:
  • Do not forget to replace arnaud.morin with your login
<?php

// Load required configuration & Emerginov Class
require_once("passwords.php");
require_once("Emerginov.php");

// Create a new Emerginov object
$Emerginov = new Emerginov($api_login, $api_password);

// Send the SMS
$res = $Emerginov->Call("arnaud.morin");

print_r($res);

?>
  • Start your VoIP client and browse the makecall.php page: http://projects.<your domain>/<project>/makecall.php

PSTN/PLMN management

If you configured a gateway or a SIP trunk (see gateway page)

  • Connect as <admin> on the admin portal => http://www.<your domain>/admin
  • Select VoIP menu (same creds)
  • Select the menu System > Dialplan
  • Add New rule and associate a routable number to my <my project>
  • Click on Apply changes to server

SMS tests

We assumed that the SMS gateway has been installed (see gateway page )

SMS sending

  • Log in as user <user> on your selfcare https://<domain>/main_authen/selfcare.php
  • Click on your <project>
  • Click on the API shop tab
  • Select Send SMS
  • Put your quota then click on OK
  • Click on Save the modifications
  • Log out as <user> then connect as <admin> on the admin portal => http://www.<your domain>/admin
  • Click on Projects API
  • Select <project>
  • Click on Accept subscription
  • Click on Save last settings
  • Log out as admin and log in as user <user> on your selfcare https://<domain>/main_authen/selfcare.php
  • Click on your <project>
  • Edit, modify and save the index.php of <your project> (svn online client)
<?php
require_once ("Emerginov.php");
require_once ("passwords.php");

if (isset($_GET['numero'])){
$Emerginov = new Emerginov($api_login, $api_password);
       
  $ret = $Emerginov->SendSMS($_GET['numero'],$_GET['text']);
   echo "<pre>";
       print_r($ret);
   echo "</pre>";
}

?>
<form method='get'>
<input type="text" name="numero" value="+33" />
<input type="text" name="text" value="" />
<input type="submit" value="Appel!" />
</form>
  • Go on http://projects.<your domain>/<project>/
  • Fill in the form => you shall receive a SMS

SMS reception

  • Log in as user <user> on your selfcare https://<domain>/main_authen/selfcare.php
  • Click on your <project>
  • Click on the API shop tab
  • Select Receive SMS
  • Click on OK
  • Click on Save the modifications
  • Connect as <admin> on the admin portal => http://www.<your domain>/admin
  • Click on Projects API
  • Click on your <project>
  • Click on Accept subscription
  • Click on Save last settings
  • Log out as admin and log in as user <user> on your selfcare https://<domain>/main_authen/selfcare.php
  • Click on your <project>
  • On the Configuration tab, in API configuration section, the keyword <project> and the callback URL shall be indicated (By default http://projects.<your domain>/<project>/smsreceiver.php)
  • Logs shall be displayed in http://projects.<your domain>/<project>/log

Mails tests

Sending mails

  • Log in as user <user> on your selfcare https://<domain>/main_authen/selfcare.php
  • Edit, modify and save the mailsender.php file. The default file should be like this one:
<?php
/*
 * This file has automacally been created by Emerginov Project Creation mecanism.
 * The purpose of this file is to provide a sample incoming voice call management.
 * Please edit the file to handle properly your incoming voice calls.
 * You might find many information on how to do so on Emerginov wiki.
 * http://emerginov.ow2.org/xwiki
 */

// Send a mail - browse http://www.yopmail.com/ to see the mail
$r = mail("emerginov@yopmail.com", "This is a test mail", "Hello,\n\nThis mail has been sent from your Emerginov project!\n\nBye!");
if ($r) echo 'Mail has been sent, please check mail on: <a href="http://www.yopmail.com/">http://www.yopmail.com/</a><br/>Account is "emerginov"';
else echo 'An error occured while trying to send a mail';
?>
  • Go on http://projects.<your domain>/<project>/mailsender.php
  • Check that mail has been received on http://www.yopmail.com/

Receiving mails

This function is not yet available