FusionForge

Difference between revisions of "Virtual machine development environment"

From FusionForge Wiki
Jump to: navigation, search
(Running the test suite: no more details "below", it's in the right section)
(Simplify the initial install some more.)
Line 14: Line 14:
 
(Note: if you wish, you can extract the disk image from the <tt>.box</tt> and use it with KVM, see below.)
 
(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 ==
+
== Starting the VM with Vagrant ==
  
Note: installing the VM requires some free space (~700MB in your <tt>~/.vagrant.d/</tt> and ~1.5GB in <tt>~/VirtualBox VMs</tt>) :
+
Note: installing the VM requires some free space (~700MB in your <tt>~/.vagrant.d/</tt> and ~1.5GB in <tt>~/VirtualBox VMs</tt>).
  
# configure Vagrant:
+
* Save this [https://fusionforge.org/plugins/scmgit/cgi-bin/gitweb.cgi?p=fusionforge/fusionforge.git;a=blob;f=vm/Vagrantfile-sample;hb=HEAD Vagrant configuration] as <tt>Vagrantfile</tt>, in a directory of your choice.
vagrant init fusionforge-dev-debian http://fusionforge.fusionforge.org/sandbox/fusionforge-dev-debian.box
+
* Edit the Vagrantfile if needed (e.g. if <tt>192.168.35.11</tt> is already taken on your network)
 
+
* In your host's <tt>/etc/hosts</tt>, add:
# optionaly modify 'Vagrantfile', see below
+
192.168.35.11 forge.internal lists.forge.internal scm.forge.internal users.forge.internal
 
+
* Download, create and start the VM with:
# download, create and start the VM:
 
 
  vagrant up
 
  vagrant up
 
+
* You now can login without a password:
# you now can login without a password:
 
 
  vagrant ssh -- -l root
 
  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 customized 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 lists.forge.internal scm.forge.internal users.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.
 
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.
Line 46: Line 31:
 
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.
 
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 ==
+
== Building and installing FusionForge ==
 
 
This VM/appliance helps you test FusionForge, and possibly start contributing.
 
 
 
It's basically a clean Debian system (wheezy/stable), with a git clone/checkout of the FusionForge code and a few helper scripts.
 
  
The VM currently runs the [https://fusionforge.org/plugins/scmgit/cgi-bin/gitweb.cgi?p=deb-packaging/deb-packaging.git;a=shortlog;h=refs/heads/debian/5.3 debian/5.3], checked-out in <tt>/usr/src/fusionforge/</tt> - that's where you should do the changes you want to test.
+
This VM/appliance is basically a clean Debian system (wheezy/stable), with a git clone/checkout of the FusionForge [https://fusionforge.org/plugins/scmgit/cgi-bin/gitweb.cgi?p=deb-packaging/deb-packaging.git;a=shortlog;h=refs/heads/debian/5.3 debian/5.3] code in <tt>/usr/src/fusionforge/</tt>.
  
The helper scripts are in the <tt>/usr/src/fusionforge/vm/scripts</tt> directory.
+
To build and install FusionForge, you just need to run helper scripts from the <tt>/usr/src/fusionforge/vm/scripts/</tt> directory, in order:
We recommend you run these scripts in this order:
 
  
 
* '''<tt>update.sh</tt>''' will update the sources from Debian FusionForge's Git repository, and also the currently installed packages.
 
* '''<tt>update.sh</tt>''' will update the sources from Debian FusionForge's Git repository, and also the currently installed packages.
Line 156: Line 136:
 
http://fusionforge.fusionforge.org/sandbox/fusionforge-dev-centos.box
 
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.
+
However there are no scripts for this version. You need to build and install FusionForge manually.
  
 
== Modify the VM ==
 
== Modify the VM ==

Revision as of 19:06, 2 June 2014

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 packaged and installed using included automated scripts.

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

Starting the VM with Vagrant

Note: installing the VM requires some free space (~700MB in your ~/.vagrant.d/ and ~1.5GB in ~/VirtualBox VMs).

  • Save this Vagrant configuration as Vagrantfile, in a directory of your choice.
  • Edit the Vagrantfile if needed (e.g. if 192.168.35.11 is already taken on your network)
  • In your host's /etc/hosts, add:
192.168.35.11 forge.internal lists.forge.internal scm.forge.internal users.forge.internal
  • Download, create and start the VM with:
vagrant up
  • You now can login without a password:
vagrant ssh -- -l root

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 alternative with port redirection below.

Building and installing FusionForge

This VM/appliance is basically a clean Debian system (wheezy/stable), with a git clone/checkout of the FusionForge debian/5.3 code in /usr/src/fusionforge/.

To build and install FusionForge, you just need to run helper scripts from the /usr/src/fusionforge/vm/scripts/ directory, in order:

  • update.sh will update the sources from Debian FusionForge's Git repository, and also the currently installed packages.
  • build.sh automatically builds FusionForge Debian packages from the sources, and stores them in a local package repository in /usr/src/debian-repository/.
  • install.sh installs those FusionForge packages.

You now have an up-to-date FusionForge running on http://forge.internal/ ! The fusionforge administrator's web login is admin and its password is myadmin.

Running the test suite

The VM is ready to run the functionnal 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.

A couple other scripts run the test suite:

  • install-gui.sh optionally sets up an X11 graphical environment.
  • run-testsuite.sh installs Selenium and runs the testsuite

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

Tests need around 25mn to complete, depending on the computing power of your machine. Failure screenshots are stored in /var/log/.

Running graphical programs remotely

If you don't want to install a full GUI on the VM (i.e. not using install-gui.sh), 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: /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:

[core]
http_port=8080
https_port=8443

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

127.0.0.1 forge.internal lists.forge.internal scm.forge.internal users.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 the development Git branch

If you want to use the latest development branch (to contribute to FusionForge or test the unreleased features), you can:

cd /usr/src/fusionforge/
git checkout debian/master

Note: if you switch back to an earlier version (e.g. from development back to stable), make sure you uninstall your FusionForge first because the packages won't be downgraded automatically:

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 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 no 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/.

Links