[[TOC]]
= Installation Guidelines: Virtual Machine =

'''''These instructions go along with the custom virtual machine image supplied for the GHC Codeathon. Its copy of the Eden repository points to the GHC team repository on !GitHub.'''''[[BR]]

The most convenient way to get up and running is to use a pre-configured development kit -- a complete operating system that's been set up to include all the required code and tools, and saved as an image of the system's disk -- and run this "virtual system" (sometimes called an "appliance") in a "virtual machine" (VM). The virtual machine runs as an application on your machine -- the "host" machine -- and emulates a separate computer -- the "guest" machine. You won't have to install anything but the virtual machine directly on your system. (We're including the official virtual machine jargon in case you need to read virtual machine documentation. We'll use "VM" to refer to the guest virtual machine. The virtual machine "manager" will be the tool that is used to configure and start your VM.)

== Copy the files you need off the flash drive ==

 * Everyone should copy:
  * The readme file {{{README_GHC.txt}}}
  * The virtual machine image {{{EdenDevEnvGHC.ova}}}.
  * The docs directory {{{Docs}}}.
 * Mac users copy the {{{Mac}}} directory.
 * Windows users copy the {{{Win32}}} directory.

Now give the flash drive to the next person waiting for it.

== Install !VirtualBox ==

=== If you're installing on Mac or Windows ===

 * Mac and Windows users have !VirtualBox installers from the flash drive, in directories {{{Mac}}} or {{{Win32}}}, respectively.
 * Run the installer (by whatever means is appropriate for your system).
  * Let it install all features.
  * The installation will temporarily disconnect your machine from the network -- take appropriate action before letting the installer proceed if you are running something that can't tolerate being disconnected.
 * (Windows users: You don't need those "extensions" unless you want to use the USB drive from your virtual machine. You can always install them later.)

=== If you're installing on Linux ===

 * Linux users should download the appropriate '''[https://www.virtualbox.org/wiki/Linux_Downloads VirtualBox installation file]''' for your system, and follow instructions there.

== Import the image into the virtual machine ==

 * Start !VirtualBox Manager (or let the installer start it).

 * Give !VirtualBox Manager the image to run:
  * Select File -> Import Appliance.
  * Click the Choose button. Navigate to and select EdenDevEnvGHC.ova.
  * Click Next (or Open, for a Mac).
  * (Do not uncheck any options on the appliance options form.)
  * Click Import.

== Connect to the network ==

Next tell the VM about your machine's network interface, so the guest can get to the network.

 * Scroll down on the right side of !VirtualBox Manager until you see Network -- click that.
 * If no adapters are enabled, enable adapter 1.
 * For "Attached to" select "Bridged Adapter". 
 * Under that, for "Name", select the appropriate network interface, e.g. wireless if that's what you're using. (Keep this setting in mind -- you may need to change it if you sometimes use a wired network, and sometimes wireless.)

== Start the virtual machine ==

On the left side of the !VirtualBox Manager GUI, you should see your new "Eden Dev Env" virtual machine.

* Double-click the virtual machine entry to start it.
* As it starts up, it may show popups about "mouse / keyboard capture". Check "Don't show this again" and dismiss the popups.
* The Login screen should appear. User is ''dev'' and password is ''eden''.
* After you're logged in, the Eclipse IDE will start -- ignore it for the moment.

== You may want to change the dev password. ==

* Start a terminal window by double-clicking the !LXTerminal icon.
* To change your password, type {{{passwd}}} and follow the instructions.

== Fix these before starting Eden ==
* Install the dateutil library:[[br]]
  {{{
sudo apt-get install python-dateutil
}}}
* Get a fresh copy of the configuration file:
 * In Eclipse, find {{{web2py/applications/eden/models/000_config.py}}} and delete it (right-click (or Mac equivalent), delete).
 * Also in Eclipse, find {{{web2py/applications/eden/deployment-templates/models/000_config.py}}} and copy it to {{{web2py/applications/eden/models/000_config.py}}}.
 * Edit {{{web2py/applications/eden/models/000_config.py}}} and change the first "False" to "True" -- that's this line:[[br]]
   {{{
FINISHED_EDITING_CONFIG_FILE = True
}}}

== Update Eden if needed ==

If you arrived at the beginning of the Codeathon, you don't need to do this. If you started later, and people might have started updating the team Eden branch on Launchpad, then make sure you have all of their work by doing:

 * (If you don't have one open) start a terminal window by double-clicking the !LXTerminal icon.
   {{{
cd /home/web2py/applications/eden
git pull upstream
}}}

== Next steps ==

'''''Installation is complete here.'''''

* Have a look at the rest of the [wiki:Develop developer's wiki].
* Try out this [http://en.flossmanuals.net/sahana-eden/building-a-new-application/ familiarization exercise].

'''''Go hack! Success! '''''