Virtual machine development environment

From FusionForge Wiki
Revision as of 19:01, 27 April 2014 by Beuc (talk | contribs) (Tips)

Jump to: navigation, search

We provide a 64 bit development/tests virtual machine (aka FusionForge Sandbox) with an already configured automated tests environment. FusionForge is not pre-installed, it is automatically "built" using included scripts.

Note that you'll need a rather recent and reasonably powerful machine capable of running a virtual machine in addition of your current environment (i.e. multiprocessor and some amount of spare disk space).

Install Vagrant and VirtualBox

To use the VM, please install Vagrant (>= v1.1). By default Vagrant uses 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 /etc/apt/sources.list:

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 .box and use it with KVM, see below.)

Run 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 $HOME/.vagrant.d/ is located (around 2.2 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.
vagrant up
vagrant ssh -- -l root

You can get inspiration from vm/Vagrantfile-sample for the configuration.

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.

Contents of the VM

This VM/appliance is designed to help you get started on development. It's basically a clean Debian system (wheezy/stable), with a checkout of the FusionForge code and a few helper scripts. Those scripts are in the /usr/src/fusionforge/vm/scripts directory:

  • update.sh will update the sources from Debian FusionForge's Git repository, and also the currently installed packages.
  • build.sh builds FusionForge packages from the sources, and stores them in the package repository at /usr/src/debian-repository/.
  • install.sh installs those FusionForge packages. This should end up with an up-to-date FusionForge running on http://forge.internal/ , with the administrator's login being “admin” and its password being “myadmin”.
  • install-gui.sh optionally sets up an X11 graphical environment.
  • run-testsuite.sh installs Selenium and runs the testsuite

We recommend you run these scripts in order. There's an icon on the VM's Desktop to run build.sh+install.sh, and another one for run-testsuite.sh.

The actual source code is stored under /usr/src/fusionforge, so that's where you should do the changes you want to test.

Accessing the web interface from host - using an internal IP

In the Vagrantfile, add:

config.vm.network :private_network, ip: ""

(replace with any IP that does *not* exist)

And in your host's /etc/hosts, add: forge.internal

Then hit http://forge.internal/ !

Stalled SSH access

If user SSH access to the VM is stalling, check that nscd is installed:

aptitude install unscd

See the thread (1, 2) about this issue.

Running the test suite

(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:


Tests need around 25mn to complete. Failure screenshots are stored in /var/log/.

Running remotely

If you don't want to install a full GUI on the VM, you can also run the interesting things remotely through SSH using

vagrant ssh -- -l root -X

Note that Selenium needs an X11 display (since it drives a graphical web browser).

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.


To reset the FusionForge admin password

Use: /usr/share/gforge/bin/forge_set_password admin

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 Vagrantfile, add:

config.vm.network :forwarded_port, guest: 80,  host: 8080
config.vm.network :forwarded_port, guest: 443, host: 8443

In /etc/fusionforge/config.ini.d/zzzz-local.ini, add:


And in your host's /etc/hosts, add: forge.internal

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

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:

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 virt-manager.
  • 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 /etc/network/interfaces afterwards for replicating eth0 config stanza for eth1 for instance. You can find which device to enable by running ifconfig -a.
  • You may need to check the web_host setting in /etc/fusionforge/config.ini.d/debian-install.ini 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 Packer tool. See the Packer configuration in vm/packer/.