Changes between Initial Version and Version 1 of InstallationGuidelines/VirtualMachineConfiguration

11/11/11 09:48:09 (10 years ago)
Pat Tressel



  • InstallationGuidelines/VirtualMachineConfiguration

    v1 v1  
     3''This page is obsolete for the current virtual machine image, which is fully configured. It shows configuring a partly-set-up image. There's no reason for users to have to do this, as we can export a fully-configured image.''
     5= Installation Guidelines: Virtual Machine =
     7The 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.)
     9== Get the Sahana Eden development kit image ==
     11 * Download the current '''[ virtual machine image]'''. Size is about 400MB.
     13 * The downloaded file is compressed -- uncompress it as follows. (You should end up with a directory with a name like "Eden Dev Env".)
     14  * On Windows, a good tool for (un)compressing is '''[ 7-Zip]'''.
     15  * On Linux / Unix, do: [[br]]
     16    {{{tar xzf filename.tar.gz}}}[[br]]
     17    using the actual downloaded filename in place of filename.tar.gz.
     19== Install !VirtualBox ==
     21 * 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.)
     23 * Run the installer (by whatever means is appropriate for your system).
     24  * Let it install all features.
     25  * 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== Import the image into the virtual machine ==
     29 * Start !VirtualBox Manager (or let the installer start it).
     31 * Give !VirtualBox Manager the image to run:
     32  * Select File -> Import Appliance.
     33  * Click the Choose button. Navigate into the Eden Dev Env directory and select the .ovf file).
     34  * Click Next (or Open, for a Mac).
     35  * (Do not uncheck any options on the appliance options form.)
     36  * Click Import.
     38== Start the virtual machine ==
     40On the left side of the !VirtualBox Manager GUI, you should see your new "Eden Dev Env" virtual machine.
     42 * Click the virtual machine entry to select it.
     43 * Click Start (on the !VirtualBox Manager menu bar).
     44 * You may get several popups telling you that the VM is going to "capture" your mouse and keyboard, and the "host key" to press to free them up. Remember which one it is. (This is only needed temporarily -- mouse sharing issues get fixed later.) Click Ok to the popups.
     45 * You'll see a box asking you to enter a new "root" password. Click the mouse on the virtual machine window to give it focus. That will get you another popup telling you to let the VM "capture" your mouse. Click Ok. Your mouse pointer will disappear.
     46 * Type a new root password. Type Enter.
     47 * Retype your password. Type Enter.
     48 * On the TKLBAM box, just type Enter.
     49 * Next you'll get a box that asks you to install security updates. Updates can cause problems, so we don't want to do this now. Type Tab to highlight "Skip", then type Enter. [Note there is apparently a bug in the virtual machine at this point -- it does not skip the updates. At the moment, it takes rather a long while to complete the unwanted updates -- we're putting together an image that will not need (so many) updates.]
     50 * After the updates, you'll get a login prompt. Type "root" and Enter. For the password, type your new root password.
     51 * Next change the ''dev'' password. Type:[[br]]
     52   {{{passwd dev}}}[[br]]
     53   Enter a new password.
     54 * Reboot by typing {{{reboot}}} and then Enter.
     56Reboot will take a little while. When it's done, the VM should start its GUI.
     58 * This time, log in as ''dev'' with your new ''dev'' password.
     60== Connect to the network ==
     62Next tell the VM about your machine's network interface, so the guest can get to the network. 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]'''. This shows bridged setup (because everyone who we know who is using VirtualBox is using bridged networking...):
     64 * Scroll down on the right side of !VirtualBox Manager until you see Network -- click that.
     65 * If no adapters are enabled, enable adapter 1.
     66 * For "Attached to" select "Bridged Adapter".
     67 * 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.)
     69== Install the "guest additions" ==
     71The "guest additions" kit makes sharing the mouse and keyboard between host and guest more natural, and allows a larger screen size for the guest.
     73 * On the VM window menu: Devices -> Install Guest Additions... (This inserts a virtual CD-ROM with the guest additions installer in the virtual drive.)
     74 * Inside the VM window, start a terminal (double-click the LXTerminal icon). The following commands use "sudo" to execute privileged commands. The first use will ask you to enter your password -- that's the ''dev'' account password. Type:[[br]]
     75   {{{sudo mkdir /mnt/cdrom
     76sudo mount -t iso9660 -r /dev/cdrom /mnt/cdrom
     77cd /mnt/cdrom
     78sudo ./}}}
     80== Configure the guest system ==
     82=== Security and accounts ===
     83The ''root'' password is set through a dialog box on first boot.
     85The development environment is owned by the ''dev'' account. When first boot is complete, change its password too: Start a terminal window (from the accessories menu), and enter the command:
     87passwd dev
     90Then reboot:
     94and use the GUI to log in as user ''dev''.
     97=== Updating Web2py, Eden, and the operating system ===
     98/usr/local/bin contains three helpful scripts. To run them, start a terminal window and enter the commands below. They are in the path, so may be executed from any working directory.
     100==== Update web2py ====
     101On 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.
     102To update Web2py to the latest revision:
     106To update to a specific revision, do the following with nnnn replaced by the revision you want.
     108update_web2py nnnn
     111==== Update Eden ====
     112You will almost certainly want the latest revision of Eden.
     114update_eden # updates Eden to current revision
     116If, for some reason, you need a specific revision, do the following with nnnn replaced by the revision you want:
     118update_eden nnnn # updates Eden to revision nnnn
     121==== Optionally update the operating system ====
     122Although 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]]
     123Log in as ''dev'' and execute the following:
     125sudo apt-get update
     126sudo apt-get upgrade
     129=== Web2Py shell ===
     130One can get a Python command line with the Web2py and Eden environments loaded with this script (apologies for the odd name):
     134This executes the {{{python ...}}} command shown previously.
     136=== Eclipse ===
     137Some parts of the Eclipse and !PyDev configuration need to be done after startup:
     138 * DeveloperGuidelinesEclipse#Configuration
     142== What's in the image, and where did we hide the files? ==
     144=== Which Linux is this? ===
     146The 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.
     148The development environment is configured to launch [ LXDE], a lightweight desktop environment after the first boot.
     150=== Tools ===
     152Several useful tools installed:
     153 * Bazaar (bzr) -- revision control system used on Launchpad, where Sahana eden sources are hosted.
     154 * Firefox with Firebug for examining what is sent to the browser, and viewing HTTP messages sent to and from the browser.
     155 * Eclipse with PyDev for editing and debugging Python code.
     156 * Scripts for updating the Eden code and other tools.
     157 * iPython -- a fancier Python command line than the standard.
     158 * irssi
     160== Notes on using Linux (mainly for non-Linux users) ==
     163=== File locations ===
     164Web2py is located in /home/web2py. Eden is located in /home/web2py/applications/eden. Eclipse and PyDev are preconfigured with this information.
     166=== The root account ===
     168The ''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
     169use {{{sudo}}}.
     170In a terminal window, to execute a command with root privileges:
     172sudo command-to-execute-as-root
     174This 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.
     176To change passwords after first boot, log in as ''dev'', start a terminal window, and enter the following commands:
     178sudo passwd root #change root password
     179passwd #change dev password
     184== Procedure for making a new virtual machine image ==