View source for Virtual machine development environment

We provide a 64-bit development/test Virtual Machine (aka FusionForge Sandbox) with an already configured automated tests environment. FusionForge is not pre-installed, it is automatically packaged and installed using included automated scripts.

== Dependencies : Vagrant and VirtualBox ==

To use the VM, please [http://docs.vagrantup.com/v2/installation/ install Vagrant] (>= v1.1). By default Vagrant uses [https://www.virtualbox.org/wiki/Downloads VirtualBox] so install it too. 

If you're running Debian or Ubuntu, the easiest way is (depending on the version of the distribution you're running, packages may be unavailable):
 aptitude install vagrant virtualbox
VirtualBox recently moved to the "contrib" section, so you need to enable it in your <tt>/etc/apt/sources.list</tt>, for instance by adding something like :
 deb http://ftp.fr.debian.org/debian/ jessie main contrib

Make sure that you enabled '''hardware virtualization''' in your computer's BIOS, otherwise VirtualBox may not be able to run the VM.

(Note: if you wish, you can extract the disk image from the <tt>.box</tt> and use it with KVM, see below.)

== Running the VM with Vagrant ==

Installing the VM requires a lot of free space in the vagrant directory of the user, so make sure you have enough room where your <tt>$HOME/.vagrant.d/</tt> is located (around 2.5 Gb should do) before running these commands :

 # download the Vagrantfile :
 vagrant init fusionforge-dev-debian http://fusionforge.fusionforge.org/sandbox/fusionforge-dev-debian.box
 # optionaly modify 'Vagrantfile', e.g. enable 'vb.gui' to open the graphics display, by uncommenting the surrounding region of the ruby config file.
 vagrant up
 # after a while, downloads and instanciation of the VM will be complete, and you can login without a password :
 vagrant ssh -- -l root

See [https://fusionforge.org/plugins/scmgit/cgi-bin/gitweb.cgi?p=fusionforge/fusionforge.git;a=blob;f=vm/Vagrantfile-sample;hb=HEAD vm/Vagrantfile-sample] for a sample Vagrantfile configuration.

=== Configure accessibility of the VM web interface from host - using an internal IP ===

In the <tt>Vagrantfile</tt>, add:
 config.vm.network :private_network, ip: "192.168.35.11"
(replace 192.168.35.11 with any IP that does *not* exist)

And in your host's <tt>/etc/hosts</tt>, add:
 192.168.35.11 forge.internal

Apply changes using <tt>vagrant reload</tt>, then hit http://forge.internal/ !

If the VM doesn't start, try to launch the VirtualBox manager and start the VM manually: you'll have a more detailed error message.

Note: for an alternative with a NAT, cf. the tip [[#Accessing_the_web_interface_from_host_-_alternative_with_port_redirection|alternative with port redirection]] below.

== Contents of the Virtual Machine ==

This VM/appliance is designed to help you get started on development. It's basically a clean Debian system (wheezy/stable), with a git clone/checkout of the FusionForge code and a few helper scripts. 

By default, the code will be a clone of the <tt>debian/master</tt> branch of the Debian packaging git repository (https://fusionforge.org/plugins/scmgit/cgi-bin/gitweb.cgi?p=deb-packaging/deb-packaging.git;a=shortlog;h=refs/heads/debian/master), checked-out inside <tt>/usr/src/fusionforge/</tt>. It corresponds to a snapshot of the 'master' branch of the unstable development trunk (which might break at any time). The branches from the main/upstream repository of FusionForge are also available (see <tt>git remote -v</tt> for details). See [[#Use_a_stable_Git_branch|below]] for testing the ''stable'' branch.

The helper scripts are in the <tt>/usr/src/fusionforge/vm/scripts</tt> directory:

* '''<tt>update.sh</tt>''' will update the sources from Debian FusionForge's Git repository, and also the currently installed packages.
* '''<tt>build.sh</tt>''' builds FusionForge Debian packages from the sources, and stores them in a local package repository in <tt>/usr/src/debian-repository/</tt>.
* '''<tt>install.sh</tt>''' installs those FusionForge packages. This should end up with an up-to-date FusionForge running on the VM's port 80 (which may become available at http://forge.internal/ for instance, see bellow), with the fusionforge administrator's web login being “admin” and its password being “myadmin”.
* '''<tt>install-gui.sh</tt>''' optionally sets up an X11 graphical environment.
* '''<tt>run-testsuite.sh</tt>''' installs Selenium and runs the testsuite (more details below)

We recommend you run these scripts in this order.

There's also an icon on the VM's Desktop to run <tt>build.sh+install.sh</tt>, and another one for <tt>run-testsuite.sh</tt>.

The actual source code is stored under <tt>/usr/src/fusionforge</tt>, so that's where you should do the changes you want to test (rebuilding and installing the rebuilt packages, with <tt>build.sh</tt> and <tt>install.sh</tt>).

== Running the test suite ==

The VM is ready to run the ''functionnal'' [[Test_Suite|test suite]], which uses PHPUnit and Selenium to drive a controlled Web browser through various tests of the different features of the forge (hence ''functionnal'' tests), using its highest-level interface : its Web interface.

''Note: you don't need to do this if you just want to test FusionForge. This is for running the test suite to ensure you didn't break anything when developping.''

You can run the testsuite script in a terminal, or click on the Desktop "run testsuite" shortcut:
 /usr/src/fusionforge/vm/scripts/run-testsuite.sh
Tests need around 25mn to complete, depending on the computing power of your machine.
Failure screenshots are stored in <tt>/var/log/</tt>.

=== Running graphical programs remotely ===

If you don't want to install a full GUI on the VM (i.e. not using <tt>install-gui.sh</tt>), you can also run the interesting things remotely through SSH using
 vagrant ssh -- -l root -X

Note that since Selenium needs an X11 display (as it drives a graphical web browser), you may then see the full graphical run of the test suite on your local X display in a new Firefox window.

You may prefer running the X display inside the VM to start the selenium server, so that windows opened by the tests don't bother you.

== Tips, Issues and FAQs ==

=== To reset the FusionForge admin password ===

Use: <tt>/usr/share/gforge/bin/forge_set_password admin</tt>

=== Stalled SSH accesses ===

If user SSH access to the VM is stalling, check that nscd is installed:
 aptitude install unscd
See the thread ([http://lists.fusionforge.org/pipermail/fusionforge-general/2014-February/002548.html 1], [http://lists.fusionforge.org/pipermail/fusionforge-general/2014-March/002631.html 2]) about this issue.

=== Accessing the web interface from host - alternative with port redirection ===

A bit more complicated than using an internal IP, but doesn't need a separate IP.

In the <tt>Vagrantfile</tt>, add:
 config.vm.network :forwarded_port, guest: 80,  host: 8080
 config.vm.network :forwarded_port, guest: 443, host: 8443

In <tt>/etc/fusionforge/config.ini.d/zzzz-local.ini</tt>, add:
 [core]
 http_port=8080
 https_port=8443

And in your host's <tt>/etc/hosts</tt>, add:
 127.0.0.1 forge.internal

Then hit http://forge.internal:8080/ !

Attention : the test suite might not work well in such a configuration

=== Using psql as root ===

 su - postgres -c "psql -c 'CREATE ROLE root WITH LOGIN SUPERUSER'"

=== Use a stable Git branch ===

If you want to use the 5.3 stable branch (instead of the development branch), you can:
 cd /usr/src/fusionforge/
 git checkout debian/5.3

Note: if you already installed the development version, make sure you uninstall your FusionForge first because the packages won't be downgraded automatically to stable:
 vm/scripts/uninstall.sh
 rm -rf /usr/src/debian-repository/

=== Block outgoing e-mails ===

Useful if you're working on a database import with real user e-mails...
 iptables -A OUTPUT -p tcp --dport 25 -j REJECT --reject-with tcp-reset

== Using QEMU/KVM instead of VirtualBox ==

=== Converting from Virtualbox image format to QEMU qcow2 ===

Converting from Virtualbox image format to QEMU qcow2: convert to raw format first
 tar xf fusionforge-dev.box fusionforge-dev-disk1.vmdk
 VBoxManage clonehd -format RAW fusionforge-dev-disk1.vmdk ffsandbox.raw  # ~10GB

Then optionaly convert to QCOW2 format:
 qemu-img convert -f raw -O qcow2 ffsandbox.raw ffsandbox.qcow2

=== Running inside libvirt ===

* Create a VM by importing the created qcow2 disk image, with <tt>virt-manager</tt>.
* You may need to set manually the driver type to 'qcow2' in "disk" device section in the VM xml file (in /etc/libvirt/qemu/). In this case you need to redefine the VM xml file by: `sudo virsh -c qemu:///system define /etc/libvirt/qemu/ffsandbox.xml` then start the VM.
* You need to reconfigure network interfaces in <tt>/etc/network/interfaces</tt> afterwards for replicating <tt>eth0</tt> config stanza for <tt>eth1</tt> for instance. You can find which device to enable by running <tt>ifconfig -a</tt>.
* You may need to check the <tt>web_host</tt> setting in <tt>/etc/fusionforge/config.ini.d/debian-install.ini</tt> to adjust the forge's URLs for redirections.

== CentOS variant ==

A version of the VM for CentOS 6 is available:
http://fusionforge.fusionforge.org/sandbox/fusionforge-dev-centos.box

However there are not scripts for this version. You need to build and install FusionForge manually.

== Modify the VM ==

The VM is automatically generated from scratch using the [http://www.packer.io/ Packer] tool.
See the Packer configuration in <tt>vm/packer/</tt>.

== Links ==

* [http://lists.fusionforge.org/pipermail/fusionforge-general/2010-November/001245.html Original announcement]
* [http://lists.fusionforge.org/pipermail/fusionforge-general/2014-January/002539.html Vagrant/Packer announcement]