-
Notifications
You must be signed in to change notification settings - Fork 4
Installation on a production host
The following gives you a step-by-step introduction on how to get the full Voice stack up and running on a physical server. This usually takes about an hour.
Please keep in mind, that we don't consider the Voice platform to be production ready at this point. However, it survives our default call cycle simulations without hiccups over several days. You'll find a list of limitations/known issues in the wiki.
We're testing our production environment on a paravirtualized machine with 4 dedicated virtual cores and 16GByte of memory. This works out pretty well for up to 50 parallel calls. Generally, we recommend a physical host for serious installations, because we expect the timer accuracy and the effect of the low-latency kernel to be more prominent.
Foundational layer of the stack is currently a Ubuntu 14.04 amd64 Iso. Mount that to your host and boot into it. The setup will overwrite all former contents of the attached hard drives, so backup your current files before you start.
Choose the default installation from the menu. Any location and timezone should work fine, just make sure that you take a locale with utf-8 support, e.g. en_US.UTF-8.
Take wim for the login user name. Use any password — it will be removed after the initial provisioning. If you decide to name the user differently than wim, remember to change the entry in the seeds/node.json accordingly later.
Enter the hostname that your machine will be reachable at. We'll take voice for this example. If you already have a DNS entry at hand, you can use that as well. Again, this value has to be reflected by the node.json file for provisioning (see below).
If the setup detects its surrounding network via DHCP, you should take that option. Just make sure, it's not using the NetworkManager mechanism (afaik, only used for desktop installations), but the old-school /etc/network/interfaces file. If no networks are found at this point, just skip that configuration — we can add it later.
For the partitioning layout we recommend going with the guided LVM option that takes the whole available HDD, unless you have any special needs. A base installation will require about 6Gbyte free space and the volume needed during maintenance will vary dependent on your use case.
From the package selection, choose only the OpenSSH server. All other components will be installed by the chef-recipes during the initial provisioning.
Finally copying of the system files will start and we have to wait for that to finish. Once this is done, reboot the machine.
You should now be able to login as the Unix user wim that you created earlier. If you already configured the network with the setup, you can skip the next step.
If you need to configure the network, switch to root, edit the interfaces file and reboot. We give an example here — obviously, you have to adapt that for your environment:
$ sudo su -
# vi /etc/network/interfaces
auto lo
iface lo inet loopback
dns-nameservers 80.237.128.144 80.237.128.145
auto eth0
iface eth0 inet static
address 91.250.81.254
netmask 255.255.255.255
broadcast 0.0.0.0
up route -A inet add 169.255.30.1 dev eth0
up route -A inet add default gw 169.255.30.1
# shutdown -r now
-> system reboots
$ ping google.com
PING google.com (173.194.112.128) 56(84) bytes of data.
64 bytes from fra07s31-in-f0.1e100.net (173.194.112.128): ...
Now try to login via ssh. Let's create an alias on the local machine for that purpose. As HostName simply take the IP address of the remote host or the FQDN, in case you have a DNS entry. We'll use voice.dokmatic.com in this example:
> vi ~/.ssh/config
Host voice
HostName voice.dokmatic.com
User wim
> ssh voice
Welcome to Ubuntu 14.04.1 LTS (GNU/Linux 3.13.0-32-generic x86_64)
...
wim@voice:~$
Because the ability to login remotely with a password will be removed during later installation, it's necessary to put your public SSH key in place. For both wim and root, paste your public key to ~/.ssh/authorized_keys:
$ mkdir ~/.ssh && chmod 700 ~/.ssh
$ echo 'ssh-rsa YOURKEY... [email protected]' > ~/.ssh/authorized_keys
$ sudo su -
# mkdir ~/.ssh && chmod 700 ~/.ssh
# echo 'ssh-rsa YOURKEY... [email protected]' > ~/.ssh/authorized_keys
Finally check, whether you can access the remote host without password as wim and as root. Once this is done, we can go to the final step and start the platform provisioning.
> ssh voice
...
wim@voice:~$ exit
> ssh root@voice
...
root@voice:~#
Now, as root, get the latest apt packages and install the lowlatency kernel. This kernel type offers a special scheduler and 1000Hz timer resolution:
# apt-get -y update && apt-get -y dist-upgrade
# apt-get -y install git linux-lowlatency linux-headers-lowlatency linux-image-lowlatency
To prevent the system from booting into graphical mode we set some grub defaults: add the word text to the GRUB_CMDLINE_LINUX_DEFAULT value and run update-grub:
# vi /etc/default/grub
GRUB_CMDLINE_LINUX_DEFAULT="text"
# update-grub
Make sure to use the correct locale for the installation and add the following lines to /etc/environment. Ruby will take these up and treat our source files correctly:
# vi /etc/environment
LANGUAGE=en_US.UTF-8
LC_ALL=en_US.UTF-8
LANG=en_US.UTF-8
Finally, remove the password of the wim-user and reboot into the new kernel:
# passwd wim -l
# shutdown -r now
After you restarted the machine you can see the new kernel running:
# uname -a
Linux voice 3.13.0-39-lowlatency #66-Ubuntu SMP PREEMPT ...
You may want to remove the former installation kernels. It's not strictly necessary, but will save some time during upcoming kernel updates:
# KVER=$(uname -r | sed 's/[-a-z]*$//')
# dpkg -l | grep '\-3.13.0' | grep -v $KVER | awk '{print $2}' | xargs apt-get -y purge
# apt-get -y purge linux-headers-$KVER-generic linux-image-$KVER-generic linux-image-extra-$KVER-generic linux-headers-generic linux-image-generic linux-headers-server linux-generic linux-server
Now that we successfully prepared the underlying Ubuntu linux, we can trigger the first platform setup. This is controlled by Chef-recipes, so it's as easy as cloning a repo, customizing one file and launching the chef client.
The following steps have to be taken being root on the pristine remote host:
# git clone git://github.com/fwoeck/voice.git ~/voice
# cd ~/voice
# cp -r seeds /etc/chef
# chmod 700 /etc/chef
# vi /etc/chef/node.json
The file /etc/chef/node.json needs to be modified to fit your environment before we proceed. Please refer to the configuration table to get a detailed explanation of all available options. Having finished your customization, you can install the latest chef-client package and start chef-solo:
# curl -L https://www.opscode.com/chef/install.sh | bash
# chef-solo
Depending on the capacity of your server and its network bandwidth the following process will take between 30 and 45 minutes.
It happens now and then that the very first chef-run fails during setting up one of the subprojects. This could be due to network failure when acquiring remote ruby gems. Luckily, this is easy to fix: identify the current Voice service that failed (e.g. Voice-Push or Voice-Rails) and remove its directory. Then restart the chef-client:
In case of failure during setup of a subproject (e.g. Voice-Push):
# rm -rf /opt/voice-push
# chef-solo
The Voice repo includes a self-signed SSL certificate to offer a quick start solution.
Be aware, that the provided SSL certificate is publicly available and gives no real security.
If you prefer to use your own, you can copy it over the following locations at any given time. They won't be reverted by consecutive chef-runs:
/etc/asterisk/asterisk.pem (owner asterisk, mode 0600)
/etc/asterisk/ca.crt (owner asterisk, mode 0640)
/opt/nginx/conf/server.key (owner wim, mode 0600)
/opt/nginx/conf/server.crt (owner wim, mode 0640)
/etc/postfix/cacert.pem (owner postfix, mode 0600)
If you go with the self-signed keys for now, you can add the certs/server.crt to your SSL key-chain management to avoid browser security warnings.
Congratulations! You finished the Voice platform installation on your production host.
After you did one final restart, you'll be able to connect to the stack with your SIP phone(s) and place some test calls:
# shutdown -r now
Have a look at Connecting phones and calling to see how you can register your SIP phones and make the first test calls.
The page Basic health checks shows you how to get an overview of the platform status in case you experience problems or just out of curiosity.