Changes between Version 1 and Version 2 of InstallationGuidelines/VirtualMachineGHC

11/12/11 11:08:32 (13 years ago)
Pat Tressel



  • InstallationGuidelines/VirtualMachineGHC

    v1 v2  
    22= Installation Guidelines: Virtual Machine =
     4'''''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 branch on Launchpad.'''''
    46The 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.)
    6 == Get the Sahana Eden development kit image ==
     8== Copy the files you need off the flash drive ==
    8  * Download the current '''[ virtual machine image]'''. Size is about 1GB.
     10 * Everyone should copy:
     11  * The readme file {{{README_GHC.txt}}}
     12  * The virtual machine image {{{EdenDevEnvGHC.ova}}}.
     13  * The docs directory {{{Docs}}}.
     14 * Mac users copy the {{{Mac}}} directory.
     15 * Windows users copy the {{{Win32}}} directory.
    10  * The downloaded file is compressed -- uncompress it as follows. (You should end up with a directory with a name like "Eden Dev Env".)
    11   * On Windows, a good tool for (un)compressing is '''[ 7-Zip]'''.
    12   * On Linux / Unix, do: [[br]]
    13     {{{tar xzf filename.tar.gz}}}[[br]]
    14     using the actual downloaded filename in place of filename.tar.gz.
     17Now give the flash drive to the next person waiting for it.
    1619== Install !VirtualBox ==
    18  * Download the appropriate '''[ 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.)
     21=== If you're installing on Mac or Windows ===
     23 * Mac and Windows users have VirtualBox installers from the flash drive, in directories {{{Mac}}} or {{{Win32}}}, respectively.
    2024 * Run the installer (by whatever means is appropriate for your system).
    2125  * Let it install all features.
    2226  * 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.
     27 * (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.)
     29=== If you're installing on Linux ===
     31 * Linux users should download the appropriate '''[ VirtualBox installation file]''' for your system, and follow instructions there.
    2433== Import the image into the virtual machine ==
    2837 * Give !VirtualBox Manager the image to run:
    2938  * Select File -> Import Appliance.
    30   * Click the Choose button. Navigate into the Eden Dev Env directory and select the .ovf file).
     39  * Click the Choose button. Navigate to and select EdenDevEnvGHC.ova.
    3140  * Click Next (or Open, for a Mac).
    3241  * (Do not uncheck any options on the appliance options form.)
    3342  * Click Import.
    35 == Start the virtual machine ==
    37 On the left side of the !VirtualBox Manager GUI, you should see your new "Eden Dev Env" virtual machine.
    39  * Double-click the virtual machine entry to start it.
    40  * The Login screen should appear. User is ''dev'' and password is ''EastOfEden''.
    41  * After you're logged in, the Eclipse IDE will start -- ignore it for the moment.
    43 == Change your password. ==
    45  * Start a terminal window by double-clicking the LXTerminal icon.
    46  * To change your password, type {{{passwd}}} and follow the instructions.
    4844== Connect to the network ==
    5551 * 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.)
    57 == After logging in... ==
     53== Start the virtual machine ==
    59 === Eclipse ===
    60 Some Eclipse and !PyDev configuration is needed in the current image. (This is temporary -- this section will be removed when an image is uploaded that has a configured Eclipse included.)
    61  * DeveloperGuidelinesEclipse#Configuration
     55On the left side of the !VirtualBox Manager GUI, you should see your new "Eden Dev Env" virtual machine.
    63 === Updating Web2py, Eden, and the operating system ===
     57 * Double-click the virtual machine entry to start it.
     58 * The Login screen should appear. User is ''dev'' and password is ''eden''.
     59 * After you're logged in, the Eclipse IDE will start -- ignore it for the moment.
    65 '''''GHC Codeathon participants, take note! You don't need to update anything -- skip this.'''''
     61== You may want to change the dev password. ==
    67 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 the others are needed.
     63 * Start a terminal window by double-clicking the LXTerminal icon.
     64 * To change your password, type {{{passwd}}} and follow the instructions.
    69 ==== Update web2py ====
    70 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.
    71 To update Web2py to the latest revision:
    72 {{{
    73 cd /home/web2py
    74 bzr update
    75 }}}
    76 To update to a specific revision, do the following with nnnn replaced by the revision you want.
    77 {{{
    78 cd /home/web2py
    79 bzr update -r nnnn
    80 }}}
     66=== Update Eden if needed ===
    82 ==== Update Eden ====
    83 You will almost certainly want the latest revision of Eden.
    84 {{{
     68If 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:
     70 * (If you don't have one open) start a terminal window by double-clicking the LXTerminal icon.
     71   {{{
    8572cd /home/web2py/applications/eden
    8673bzr pull
    88 If, for some reason, you need a specific revision, do the following with nnnn replaced by the revision you want:
    89 {{{
    90 cd /home/web2py/applications/eden
    91 bzr pull -r nnnn
    92 }}}
    94 ==== Optionally update the operating system ====
    95 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]]
    96 Log in as ''dev'' and execute the following:
    97 {{{
    98 sudo apt-get update
    99 sudo apt-get upgrade
    100 }}}
     76== Next steps ==
    102 -----
     78'''''Installation is complete here.'''''
    104 == Notes on the configuration ==
     80* Have a look at the rest of the [wiki:Develop developer's wiki].
     81* Try out this [ familiarization exercise].
    106 === Which Linux is this? ===
    108 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 [ TurnKey Linux's Core], which in turn is based on Ubuntu 10.04 (Lucid -- the most recent long-term support release). The machine runs [ Shellinabox], [ Webmin], and SSH/sftp as services from startup.
    110 The development environment uses [ LXDE], a lightweight desktop environment.
    112 === Bridged networking vs. NAT ===
    114 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 '''[ 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...).
    116 === Tools ===
    118 Several useful tools have been installed:
    119  * Bazaar (bzr) -- revision control system used on Launchpad, where Sahana eden sources are hosted.
    120  * Firefox with Firebug for examining what is sent to the browser, and viewing HTTP messages sent to and from the browser.
    121  * Eclipse with PyDev for editing and debugging Python code.
    122  * Scripts for updating the Eden code and other tools.
    123  * iPython -- a fancier Python command line than the standard. (Note not everyone prefers this.)
    124  * irssi
    126 == Notes on using Linux (mainly for non-Linux users) ==
    128 === File locations ===
    129 Web2py is located in /home/web2py. Eden is located in /home/web2py/applications/eden. Eclipse and PyDev are preconfigured with this information.
    131 === The root account ===
    133 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
    134 use {{{sudo}}}.
    135 In a terminal window, to execute a command with root privileges:
    136 {{{
    137 sudo command-to-execute-as-root
    138 }}}
    139 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.
    141 To change passwords after first boot, log in as ''dev'', start a terminal window, and enter the following commands:
    142 {{{
    143 sudo passwd root #change root password
    144 passwd #change dev password
    145 }}}
    147 == Procedure for making a new virtual machine image ==
    149 InstallationGuidelinesVirtualMachineMaintenance
     83'''''Go hack! Success!'''''