Express Development Environment Setup
From SIPfoundry sipXecs IP PBX, The Open Source SIP PBX for Linux - Calivia
Introduction
These instructions and scripts provide a fast path for setting up a sipXecs "main" stream development environment on an i386 32-bit Fedora 10 installation.
While there are many possible options for sipXecs, using i386 32-bit Fedora 10 is the most straightforward and the most likely to result in success.
See here for instructions on older streams and/or Fedora releases.
Have an enhancement request that isn't already on the EDE wishlist? Send it to the sipx-dev@sipfoundry.org mailing list.
Prerequisites
- A fixed IP address (either statically assigned or using DHCP with a host entry), and a DNS lookup must resolve a fully qualified domain name (FQDN) to this IP address.
- A Fedora 10 i386 32-bit install media. (Get the DVD ISO here.)
- An i386 development machine:
- at least Pentium 4 or Xeon processor @ 1.8 GHz, or equivalent;
- with at least 1 GB RAM;
- with at least 50 GB hard drive;
- with access to the internet; and
- with a console (monitor.)
Note: CentOS 5 is "best effort" supported by the EDE. Beware though that the availability of packages for CentOS is problematic, so the Step 2 script will likely break often. Fedora 10 is the recommended distribution for EDE.
Step 1. Install Fedora 10
Start installing Fedora using all the defaults, with the following exceptions (in order):
a. Please name this computer (FQDN)
Clear the default "localhost.localdomain" value, and enter a FQDN that resolves to your fixed IP address.
b. Change the packages that will be installed
When you see "The default installation of Fedora includes..." look all the way to the bottom of the screen. De-select "Customize later" by selecting "Customize now", then go to the next page.
The next page lists all the packages you can install. The only one you absolutely need is "Base" under "Base System". You probably also want one of the two packages under "Desktop Environment". De-select all other packages, and continue the installation.
(Note: If you do want one of the desktops, then do not de-select "X Window System" under "Base System".)
The installation will soon be at a point where it will chug along by itself for awhile, then prompt you to Reboot. Do so, but come back to the console because there's more to be done.
c. Complete the Setup Agent (Welcome)
This step only applies if you did install a desktop.
After rebooting the console will have a Welcome screen. This Setup Agent has some screens which you can mostly zip through without changing any of the defaults, but you will be forced to create a user. Continue to d.
d. Login to a shell as root
If you did not install a desktop, then the console will show a shell login prompt. Simply login as root.
If you did install a desktop, then the console will show a GUI login screen. Login as the user you were forced to create, then open a shell. (In Gnome, this is under Applications -> System Tools -> Terminal.) Switch to a root shell with:
su - root
e. Confirm the network settings
The Fedora 10 installation process will not give you an opportunity to specify network settings. It instead assumes you are using DHCP, which may not be the case.
DHCP with a host entry
If your DHCP server has a host entry mapping your MAC address to your IP address, then you are lucky. Your new Fedora 10 installation should have the correct network settings.
DHCP available, but you need to switch to a Static IP on the same subnet
If DHCP is available on your network, then your new Fedora 10 installation should be connected to the network. But suppose you need to switch to Static IP (on the same subnet) in order to have a fixed IP address.
The ede_fedora_staticip_root.sh script can be used in this scenario. (The network connection must be functioning in order for this to work.)
Where <IP> is the desired fixed IP address, run:
wget http://sipxecs.sipfoundry.org/rep/sipXecs/main/extras/ede/ede_fedora_staticip_root.sh chmod +x ./ede_fedora_staticip_root.sh ./ede_fedora_staticip_root.sh <IP> [FQDN]
The FQDN is optional. If omitted, the script will perform a reverse DNS lookup on the IP address and use the resulting FQDN. If there is no reverse DNS entry, or if you want a different FQDN, then you must use this option.
No DHCP
If DHCP is not available, then the network connection will have failed. You will need to manually configure the machine to use your Static IP address.
This isn't easy in Fedora 10. I was not successful in my attempts at configuring NetworkManager to do this, and ended up switching back to the network service.
See the above ede_fedora_staticip_root.sh script as a reference for what changes need to be made.
f. Confirm the FQDN (Fully Qualified Domain Name)
Fedora 10 installations seem to disregard the FQDN specified during the install (Step 1.a. above.) The FQDN that resolves to your fixed IP address must be returned from the hostname -f command in order to proceed.
Run:
hostname -f
If anything other than your FQDN is returned (such as "localhost.localdomain") then you need to manually edit the /etc/hosts file and restart the applicable service:
service NetworkManager restart
or
service network restart
(This is one of the problems fixed by the ede_fedora_staticip_root.sh script above.)
Step 2. Run the ede_base_root.sh script (as root)
Run the ede_base_root.sh script:
wget http://sipxecs.sipfoundry.org/rep/sipXecs/main/extras/ede/ede_base_root.sh chmod +x ede_base_root.sh ./ede_base_root.sh [username]
The username parameter is optional, but can be used to specify an existing user account from Step 1c above. If the username is omitted the script will create a sipxchange user account for you, password PingMe. This is the development user that you'll use to build and run sipXecs, starting in Step 3.
This script will chug along by itself for awhile.
Please report any failures of this script to the sipx-dev@sipfoundry.org mailing list. (If there are failures then this script can be re-run after the problem is corrected.)
Step 3. Get the sipXecs source (as development user)
After the reboot, log in as the development user (sipxchange/PingMe, or the user account from Step 1c above.) From this point forward you'll do all your work under this development user account.
Make a directory to hold the sipXecs source, build, and installation. You can name WORKING whatever you want, and have as many of them as you like. (This article uses "WORKING" only as an example.)
Everything (including $CODE, $BUILD, $INSTALL) will be contained in the WORKING directory. There is one exception... The TFTP server and FTP users are configured to access .../WORKING/INSTALL/var/sipxdata/configserver/phone/profile/tftproot through the /tftpboot softlink. If you switch between WORKING directories, then update the /tftpboot softlink if you want phone profiles to work.
mkdir WORKING cd WORKING
Get the sipXecs source. You will only need to run one of the following four commands, depending on your preference of git vs. subversion and whether or not you have commit rights to the sipXecs subversion repository.
Note: The git commands take longer to run, especially the last one.
No commit rights, and prefer subversion:
svn co -q http://sipxecs.sipfoundry.org/rep/sipXecs/main/
Yes commit rights, and prefer subversion:
svn co --username [username] -q https://sipxecs.sipfoundry.org/rep/sipXecs/main/
No commit rights, and prefer git:
git clone git://github.com/dkrzemin/sipxecs.git main
Yes commit rights, and prefer git:
git svn clone https://sipxecs.sipfoundry.org/rep/sipXecs/main
Step 4. Run the ede_build_devuser.sh script (as development user)
Run the ede_build_devuser.sh script:
wget http://sipxecs.sipfoundry.org/rep/sipXecs/main/extras/ede/ede_build_devuser.sh chmod +x ede_build_devuser.sh ./ede_build_devuser.sh
Please report any failures of this script to the sipx-dev@sipfoundry.org mailing list. (If there are failures then this script can also be re-run after the problem is corrected.)
This script will chug along by itself for awhile.
You will then be put into the sipXecs System Setup Wizard. You (almost surely) must change the "SIP Domain Name" on the "SIP Settings" (third) screen. The default value will be your hostname, but with the prefix removed. Add the prefix back so the value is exactly the same as your hostname.
The last screen of the wizard offers you to "Start sipXecs".
Your development environment setup is complete when the wizard exits. If sipXecs wasn't started by the wizard, then you can do so now by running 'sstart'.
Be sure to source the 'env' file to get the useful environment variable paths and Eclipse alias.
source env-ede
Command-line options
The ede_build_devuser.sh script accepts a number of command-line options:
| option | definition |
|---|---|
| -h | Print the 'usage' and exit. (Supersedes all other options.) |
| -d | Build dependency RPMs locally PWM |
| -r | Do an "RPM" build, instead of a "designer" (Makefile) build. |
| -i | Skip the (interactive) sipxecs-setup script execution. (Also skip the re-install on "RPM" builds.) |
| -c <dir> | Use the specified directory for $CODE, instead of the default "main". |
| -s | Build in "sandbox" mode, with no changes outside the WORKING directory. (Imcompatible with -d and -r RPM building.) |
Step 5. Rebuild sipXecs with your changes (as development user)
Assuming you've created the development environment for the purpose of making code changes, you can do this now.
To re-compile and re-install sipXecs:
./bin_ede/rebuild
To include the automated unit tests in a re-compile and re-install:
pushd BUILD make build popd
After a re-install you'll of course need to stop and restart sipXecs for your changes to take effect. (Use the srestart command.)
If you'd like to completely refresh your build from scratch (but keeping your existing source), simply re-run the ede_build_devuser.sh script from the WORKING directory, just as you did in from Step 4. Beware though, this will erase all your data! (Configuration, device files, and generated profiles.)
To re-run autoreconf and configure, then re-compile and re-install sipXecs (without erasing your data):
./bin_ede/full_conf_build
Environment Features
Your Express Development Environment has the following features.
Eclipse readiness
The EDE is ready for Eclipse:
- An 'eclipse-workspace' directory was created.
- The sourced WORKING/env-env file created an ede-eclipse alias (which automatically uses the above workspace directory.)
- The required path variables (under Windows->Preferences) are pre-populated into your workspace, so you don't need to add them manually.
- Many of the steps from the sipXconfig Eclipse and sipXconfig remote debugging articles have already been performed.
See here for detailed instructions on using Eclipse in your sipXecs EDE.
sipXecs service start, stop, restart, and status command shortcuts
There are sstart, sstart, srestart, and sstatus scripts in /usr/bin. This directory is in your $PATH, so just run the command.
Directory of useful softlinks
There's a WORKING/links directory, which contains softlink shortcuts to number of directories that a sipXecs developer is likely to visit frequently.
Useful environment variable paths
The WORKING/env file your sourced sets a number of environment variable to full paths, for example:
- WORKING_DIR="/home/sipxchange/WORKING"
- INSTALL="/home/sipxchange/WORKING/INSTALL"
- BUILD="/home/sipxchange/WORKING/BUILD"
- CODE="/home/sipxchange/WORKING/main"
- LINKS="/home/sipxchange/WORKING/links"
- DIST="/home/sipxchange/WORKING/DIST"
Log rotation and compression
The sipXecs and FreeSWITCH logs will be rotated and compressed by the logrotate utility.
PlcmSpIp FTP write permissions
The PlcmSpIp FTP user has write permissions. This allows Polycom SoundPoint family phones to upload their user preferences and log files. The log files can be useful when diagnosing problems.
Please send all questions, comments, and suggestions to the sipx-dev@sipfoundry.org mailing list.
Happy sipXecs developing!
