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

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.)

== Get the Sahana Eden development kit image ==

 * Download the current '''virtual machine image''': [http://eden.sahanafoundation.org/downloads/EdenDevEnv.ova EdenDevEnv.ova] (2.4 Gb). Estimated time for download on a high-speed network connection is an hour (but it could take considerably longer depending on network speed and ISP policies on large downloads). Updated: 2014-09-29.
 * Note: If clicking the link does not download the file, right-click the link and select "Download Linked File" or "Save Page As...".
 * Verify the MD5 checksum and file size in bytes, to assure that the download completed correctly. Commands and correct output are shown.
  * Linux and MacOS:
{{{
wc -c EdenDevEnv.ova
2414475776 EdenDevEnv.ova

md5sum EdenDevEnv.ova
3a7e7935b3f340f780d2c07331f0a6ef  EdenDevEnv.ova
}}}
  * Windows -- two options:
   * Install the [http://support2.microsoft.com/default.aspx?scid=kb;en-us;841290 File Checksum Integrity Verifier] from Microsoft.
     (If you do not want to put this in your Path environment variable, then use the full path for fciv.exe.)
     The {{{dir}}} command will show the size in bytes. (The date and other {{{dir}}} output are not relevant, and the size
     may be formatted differently per locale.)
{{{
fciv.exe EdenDevEnv.ova
//
// File Checksum Integrity Verifier version 2.05.
//
3a7e7935b3f340f780d2c07331f0a6ef edendevenv.ova

dir EdenDevEnv.ova
...
09/29/2014  06:08 AM     2,414,475,776 EdenDevEnv.ova
...
}}}
   * Or, if you have Cygwin, use the Linux commands above.
== Install !VirtualBox ==

 * Download the appropriate '''[https://www.virtualbox.org/wiki/Downloads VirtualBox binary and extension pack]''' for your system. (You won't need the SDK.)

 * Run the installer (by whatever means is appropriate for your system).
  * Let it install all features.
  * Note: The installation will temporarily disconnect your machine from the network.

== Import the image into the virtual machine ==

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

 * Give !VirtualBox Manager the image to run:
  * File -> Import Appliance. '''[http://www.freeimagehosting.net/45utn screenshot]'''
  * Click the Open appliance... button. Navigate to the !EdenDevEnv.ova file and select it. '''[http://www.freeimagehosting.net/dflyg screenshot]'''
  * Click Next (or Open, for a Mac).
  * (Do not uncheck any options on the appliance options form.)
  * Click Import.  '''[http://www.freeimagehosting.net/6ddvf screenshot]'''
  * Wait for the Import process to finish. '''[http://www.freeimagehosting.net/u1a3h screenshot]''' Estimated time:5 minutes

== 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 the link on the word "Network" to open the Network panel. (This may take a minute to load.)
 * If no adapters are enabled, enable adapter 1.
 * For "Attached to", you have an option:
   * NAT will work in all cases, so is the default. It does not support using your VM as a server to be accessed from other machines.
   * "Bridged Adapter" will generally work with a wired Internet connection, but may not work on all WiFi networks
   * When in doubt, chose NAT. If you try Bridged and the network is not available in the virtual machine, shut it down and change this to NAT. (The first symptom of no network may be an error in automated update checking.)
 * 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 "!EdenDevEnv" virtual machine.

 * Double-click the virtual machine entry to start it. '''[http://www.freeimagehosting.net/3rynj screenshot]'''
 * The default user will be automatically logged in. The default user's username and initial password are:
  * User: ''dev''
  * Password: ''eden''
 * If a Linux update window has popped up, click "Ask Me Later" to dismiss it (see below for more information on updating Linux). [http://www.freeimagehosting.net/oblz2 screenshot]
== You may want to change the dev password. ==

 * Start a terminal window by double-clicking the LXTerminal icon. (It may be hidden by popup windows at the top of the screen at first.)
 * To change your password, type {{{passwd}}} and follow the instructions.

== Conditionally update Web2py, Eden, and the operating system ==

The Eden code is updated (much) more frequently than is the VM image, so the Eden branch supplied in the image will be out of date.  So, too, will be Web2py and the Linux distribution, but those will typically not need frequent updating. We recommend only updating Eden, unless you know that new versions of Web2py or the Linux distribution are needed.

''Note '''if you are using a wireless network that redirects to a login form or "terms and conditions" page''', then before you use git to update Eden and Web2py, '''start Firefox and (attempt to) go to any site, so you can take care of logging in or signing up''' with the wifi provider.  Otherwise git, which uses https, will get redirected to the login form, and you'll get an error indicating that the wifi provider's site is not !GitHub...''

''Note you may get a warning about being unable to find SSH keys. No keys are set up initially, but later if you want to submit changes on !GitHub, you nay want to set up your own SSH keys instead of using your !GitHub username and password in the git command.''
==== Update Eden ====

Start a terminal window by double-clicking the !LXTerminal icon.

You will almost certainly want the latest revision of Eden:
{{{
cd /home/web2py/applications/eden
git pull origin master
}}}

(If / when you set up your own !GitHub repository that is a "fork" of the main Eden repository, you'll want to change the name of the main Eden repository from "origin" to "upstream", so that you can use "origin" to refer to your own repository.)

If you are working on a specific branch for a particular event (e.g. RHoK), then you can add that branch to your repository:
{{{
cd /home/web2py/applications/eden
git remote add <branch_name> https://github.com/flavour/<branch_name>.git
git fetch <branch_name>
}}}
Now you have both the trunk ("master" branch) and the specific branch <branch_name> in your local repo.

If, for some reason, you need a specific revision of the current branch, do the following:
{{{
cd /home/web2py/applications/eden
git checkout -b <revision> <branch_name>
}}}
(git requires a name for a branch if you want to preserve commits.)
==== Update web2py ====
To update Web2py to the latest revision:
{{{
cd /home/web2py
git pull origin master
}}}
On occasion, the latest revision of Web2py is not stable, or is incompatible with the current version of Eden.
Check the topic in the #sahana-eden IRC channel on freenode for the latest known-safe revision.
The following shows checking out a specific revision as the master branch, by first renaming master,
then checking out the desired revision as master, then getting rid of the former master branch.
{{{
cd /home/web2py
git branch -m master latest_master
git checkout -b <recommended_revision> master
git branch -D latest_master
}}}

==== Optionally update the operating system ====
'''''Caution -- this is no longer recommended as standard procedure.'''''
If the Linux kernel is upgraded, that will de-install the VirtualBox "guest additions" package, which enables such things as file sharing between the host and guest, and copy-and-paste between the host and guest. Procedures for re-installing it are linked below.

Although it's usually good advice to update the operating system and applications to pick up security fixes, updating may lead to incompatibilities with other software, and has been known to render the system unusable. So do the following only if you know there is a security issue or need more recent software, and not when you're in the middle of something critical.[[br]]
{{{
sudo apt-get update
sudo apt-get upgrade
}}}

After this, you will need to re-install the VirtualBox "guest additions" following [https://www.virtualbox.org/manual/ch04.html#idp54211856 these instructions], which differ per host operating system.

== Next steps ==

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

Next, start Web2py and Eden.

* Compare the files {{{web2py/applications/eden/models/000_config.py}}} and {{{web2py/applications/eden/modules/templates/000_config.py}}}. If there are any changes in the {{{modules/templates/000_config.py}}} file, update the {{{models/000_config.py}}} file with those changes.

* Start Web2py in Eclipse's Debug configuration. To do this, open Eclipse, open Web2Py by clicking "File," then "Open File," then selecting Web2Py.py in the Web2Py directory. Then click on "Run" in the toolbar and "Debug." [http://www.freeimagehosting.net/q6euj screenshot]

* Access the application using Firefox. To do this, make sure the application is currently running in Eclipse, then open Firefox and type in the Web2Py URL, "127.0.0.1:8000". 

* 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].

-----
== Notes on the configuration ==

These are a few notes on what's included, Linux usage, etc. They're not part of the installation.

=== Which Linux is this? ===

The virtual machine image is based on Lubuntu -- a lightweight distribution derived from Ubuntu, using the LXDE desktop manager. It is configured to use about 1024MB of RAM with a dynamically-sized virtual disk which can expand to 10GB. The virtual machine is built on [https://help.ubuntu.com/community/Lubuntu/GetLubuntu the latest Lubuntu ISO], which in turn is based on Ubuntu 13.04 (Raring Ringtail -- the most recent long-term support release). [http://lxde.org LXDE] replaces the Unity desktop manager.

=== Bridged networking vs. NAT ===

There are two options for having the host and guest share the physical interface, NAT or bridged. NAT is less obtrusive but bridged provides more capability to the guest. For instance, with a bridged connection, one can run a server in the guest that can be accessed from other machines. See this discussion of the '''[http://www.virtualbox.org/manual/ch06.html differences between NAT and bridged modes]'''. The installation procedure offers an option, but recommends NAT to start with, as it works with more network arrangements. In particular, '''''NAT works with !WiFi, where bridged may not'''''.

=== Tools ===

Several useful tools have been installed:
 * git - Version control system. Hosting is provided by  '''[http://eden.sahanafoundation.org/wiki/DeveloperGuidelines/Git GitHub]'''
 * Firefox with Firebug for examining what is sent to the browser, and viewing HTTP messages sent to and from the browser.
 * Eclipse with !PyDev for editing and debugging Python code.
 * Scripts for updating the Eden code and other tools.
 * iPython -- a fancier Python command line than the standard. (Note not everyone prefers this.)
 * irssi - IRC chat client '''[http://en.wikipedia.org/wiki/Irssi more in wikipedia]'''

== Notes on using Linux (mainly for non-Linux users) ==

=== File locations ===
Web2py is located in /home/web2py. Eden is located in /home/web2py/applications/eden. Eclipse and !PyDev are preconfigured with this information.

=== The root account ===

The ''root'' account is the privileged user on Linux, but you don't need to log in as root to perform privileged tasks like installing software.  You can act as root without knowing the root password with the {{{sudo}}} command -- the ''dev'' account has the privilege to
use {{{sudo}}}.
In a terminal window, to execute a command with root privileges:
{{{
sudo command-to-execute-as-root
}}}
This will prompt for a password if {{{sudo}}} hasn't been run recently -- it is asking for the current user's password -- here, that's the ''dev'' password.

To change passwords after first boot, log in as ''dev'', start a terminal window, and enter the following commands:
{{{
sudo passwd root #change root password
passwd #change dev password
}}}

== Procedure for making a new virtual machine image ==

InstallationGuidelines/VirtualMachine/Maintenance