[[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 '''[http://eden.sahanafoundation.org/downloads/EdenDevEnv.ova virtual machine image]'''. Size is 1.2 Gb. Estimated time for download:30 min. Updated: 2012-10-27. * Note: If clicking the link does not download the file, right-click the link and select "Download Linked File." == Install !VirtualBox == * Download the appropriate '''[https://www.virtualbox.org/wiki/Downloads VirtualBox binary]''' for your system. (You won't need the SDK, and would only need the "extension pack" if you want to use a USB device from your virtual system. You can add it later if so.) * 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: * Select File -> Import Appliance. '''[http://www.freeimagehosting.net/45utn screenshot]''' * Click the Choose 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 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. '''[http://www.freeimagehosting.net/3rynj screenshot]''' * 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: ''dev'' * Password: ''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. == 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. ==== 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 }}} 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 BRANCHNAME https://github.com/flavour/BRANCHNAME.git git fetch BRANCHNAME }}} Now you have both, the trunk ("master" branch) and the specific branch ("BRANCHNAME" branch) in your local repo. You can switch between them: {{{ git checkout master or git checkout BRANCHNAME }}} If, for some reason, you need a specific revision of "master"/trunk, do the following: {{{ cd /home/web2py/applications/eden git checkout }}} ==== Update web2py ==== On occasion, the latest revision of Web2py is not stable. Check the topic in the #sahana-eden IRC channel on freenode for the latest known-safe revision. To update Web2py to the latest revision: {{{ cd /home/web2py git pull }}} To update to a specific revision, do the following with nnnn replaced by the revision you want. {{{ cd /home/web2py git checkout }}} ==== Optionally update the operating system ==== 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, and not when you're in the middle of something critical.[[br]] Log in as ''dev'' and execute the following: {{{ sudo apt-get update sudo apt-get upgrade }}} == Next steps == '''''Installation is complete here.''''' * Run the application using Eclipse's Debug mode. * Edit {{{web2py/applications/eden/models/000_config.py}}} to say that you've finished editing. * Access the application using Firefox. To do this, make sure the application is currently running in Eclipse, then open Firefox and select "Sahana Eden local." * 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 a [BluePrintlivecdinstaller blueprint] and is configured to use about 512MB of RAM. The virtual disk is configured to expand to 20GB. The virtual machine is built on [http://www.turnkeylinux.org/core TurnKey Linux's Core], which in turn is based on Ubuntu 10.04 (Lucid -- the most recent long-term support release). The machine runs [http://code.google.com/p/shellinabox/ Shellinabox], [http://www.webmin.com/ Webmin], and SSH/sftp as services from startup. The development environment uses [http://lxde.org LXDE], a lightweight desktop environment. === 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. See this discussion of the '''[http://www.virtualbox.org/manual/ch06.html differences between NAT and bridged modes]'''. The installation procedure shows bridged setup (because everyone who we know who is using !VirtualBox is using bridged networking...). === 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 == InstallationGuidelinesVirtualMachineMaintenance