wiki:InstallationGuidelines/VirtualMachine

Version 3 (modified by Pat Tressel, 13 years ago) ( diff )

--

Table of Contents

  1. Get the Sahana Eden development kit image
  2. Install VirtualBox
  3. Import the image into the virtual machine
  4. Connect to the network
  5. Configuration of the guest system
  6. Notes
    1. Getting Started
      1. VirtualBox Installation
        1. Troubleshooting VirtualBox
      2. VMWare Installation
        1. Troubleshooting VMware Tools Install
    2. User Accounts
      1. Root User
      2. Secure the System
    3. Filesystem
    4. Scripts
      1. Update web2py
      2. Update Eden
      3. Web2Py shell
  7. Troubleshooting older Releases

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 appliance" in a "virtual machine". 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.)

The development kit is a Debian Linux system with several useful tools installed:

  • Bazaar (bzr) -- revision control system used on Launchpad, where Sahana eden sources are hosted.
  • Firefox with Firebug for viewing HTTP messages sent to and from the browser.
  • Eclipse with PyDev for editing and debugging Python code.

Get the Sahana Eden development kit image

  • The image is compressed -- uncompress it. The extracted file will have an .ovf extension.
    • On Windows, a good tool for (un)compressing is ​7-Zip.
    • On Linux / Unix, use tar xzf to uncompress the file, e.g. if the name of the downloaded image file is filename.tar.gz then do:
      tar xzf filename.tar.gz

Install VirtualBox

  • 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 if you are running something that can't tolerate that.

Import the image into the virtual machine

  • Start VirtualBox (or let the installer start it).
  • Give VirtualBox the image to run:
    • Select File -> Import Appliance.
    • Click on the Choose button and navigate to and select the uncompressed image (the .ovf file).
    • Click Next.
    • Accept the default appliance options unless you have a reason to make a specific change.

Connect to the network

The VM will appear in the left window pane, and the settings will appear in the right. Next 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 and simpler to set up, but bridged provides more capability to the guest. A discussion of the differences is ​here. This shows NAT setup:

  • Scroll down on the right side until you see Network -- click that.
  • Select the appropriate network interface (NIC), e.g. switch to 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.)
  • Select NAT mode.

Configuration of the guest system

Configure the included Eclipse/PyDev:

Notes

The virtual machine image is based on a blueprint and are 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.

The development environment is configured to launch ​LXDE, a lightweight desktop environment after the first boot. From LXDE, Eclipse with Pydev, Firefox with Firebug, iPython and irssi are accessible.

Getting Started

  1. Download the Image
  2. Uncompress the image: ​7zip is a very effective FOSS tool for systems running Microsoft OSs. In Linux distros, the following command should work: 
    tar xvzf eden-dev-env.tar.gz (for example) #extract to current working directory

To run the image, you need to install either VirtualBox or VMWare:

VirtualBox Installation

  1. Download ​VirtualBox
  2. Install VirtualBox
  3. Import the Virtual Appliance:
  • File menu | Import Appliance
  • Click on the Choose button and navigate to and select the uncompressed image (the .ovf file)
  • Next
  • Accept the default appliance options unless you have a reason to make a specific change
  1. The VM will appear in the left window pane, and the settings will appear in the right. Scroll down on the right side until you see "Network." Click network to specify the NIC (e.g. switch to wireless) and choose between bridged and NAT mode.
  2. Start the Virtual Appliance by double-clicking the icon on the left.
Troubleshooting VirtualBox

It's been reported that VMs derived from patched ISOs, as these have, may have network problems. Read ​this article to work the solution. Contact us if you still have problems. There's no way for us to test whether there will be problems in your case.

Network Configuration

Solutions will be here.

Import Fails

Scenario

After first step of import, VirtualBox OSE 3.1.6 reports the following: "Failed to import appliance /path/to/appliance/NewDev.ofg. Too many IDE controllers in OVF; import facility only supports one."

First Solution:

  1. File | Virtual Machine Manager: Select the hard disks tab and press add disk icon. Browse to and select NewDev.vmdk. Click OK.
  2. Click the New icon. Click next. Name: NewDev; Operating System: Linux; Version: Ubuntu. Click next.
  3. Base Memory Size: 384MB. Click Next.
  4. Select "Use Existing Hard Disk"; choose NewDev.vmdk. Click Next. Click finish.
  5. Selct NewDev on the left; scroll down to network on the right. Ensure the appropriate network adapter and settings for your circumstances are selected.

Boot Process Halts

Scenario

When started in VirtualBox OSE 3.1.6, NewDev boot process halts at "Starting Initialization Hooks".

Solution

Coming soon.

VMWare Installation

Import

To import the download VM into VMware (e.g. Fusion), use the following steps.

  1. File > New
  2. Click Continue without disc
  3. Select Use an existing virtual disk
  4. Select NewDev.vmdk
  5. Select Make a separate copy of the virtual disk
  6. Click Choose
  7. Click Continue
  8. OS=Linux and Version=Ubuntu should be selected, click Continue, Click Finish
  9. Enter name for new VMware image e.g. Eden in the Virtual Machines directory
  10. Click Save
  11. Press the green play icon to start the virtual machine.

Remember to install the Linux VMware Tools after starting up the Eden machine using Virtual Machine > Install VMware Tools 

sudo su -
./vmware-install.pl

And accept all the default options

VMWware Converter Version 4.0.1: "Cannot be deployed on the target hardware"

VMware Player 3.1.1 (Ubuntu)

No File|Import option. Nor can one build a VM with a preexisting VMDK.

VMware Workstation 7.1.1

  1. File | New | Virtual Machine
  2. Custom, click Next
  3. Workstation 7.x, click Next
  4. I will install the operating system later, click Next
  5. Name: !NewVM; Location: /path/to/virtualmachines/; click Next; click Next.
  6. 360 MP; click Next
  7. Select appropriate network connection for your scenario (bridged or NAT), click Next.
  8. LSI Logic, click Next.
  9. Use an existing virtual disk; click Next.
  10. Browse to NewDev.vmdk; click Next.
  11. Finish; Close.
  12. Press the play icon or "Power on this virtual machine".
Troubleshooting VMware Tools Install
  • Open LXTerminal and browse to the folder containing vmware-install.pl. 
    pwd #displays the current location in the filesystem
cd /absolut/path/to/folder # change directory to the one containing vmware-install.pl
sudo ./vmware-install.pl #start installation script
  • Download Build Tools *Option 1: Open Synaptic in the LXDE menu, update, then search for build-essential *Option 2: Open LXTerminal and install build-essential from the command line: 
    sudo apt-get update
sudo apt-get install -y build-essential

User Accounts

Root password is set through a dialog box on first boot.

The user named dev should have it's password set from the command line when first boot is complete with the command: 

passwd dev

You should then reboot & use the Graphical User Interface to login as the user 'dev'.

Web2py administration password is set during the debugging process with either of the following commands and arguments, both of which would set the admin password to "admin": 

/home/dev/web2py.py -a admin -i 127.0.0.1 -p 80

/home/dev/web2py.py --password admin -i 127.0.0.1 -p 80

Credentials for the previous version:

Username: devPassword: eden
Username: rootPassword: root

Root User

There is no practical reason to login in as root.

If one needs root privileges, dev can have them. The following lines offer strategies for escalating devs privileges from the command line. Start LXTerminal and use one of the following strategies. 

sudo command-to-execute-as-root #executes on command or pipeline of commands as root.
su - root #Switch user to root
command to execute #1 command executed as root
command to execute #2nd command to execute as root
command to excecute #3rd command to execute as root
exit # Exit using root's account and shell

Secure the System

Change the default passwords to secure the system. Log in as dev, start LXTerminal, and enter the following commands to change passwords: 

sudo passwd root #interactive change root password
passwd #Interactive change dev password

It's also important to keep get security updates from online; login as dev and execute the following: 

sudo apt-get update
sudo apt-get upgrade

Filesystem

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

Scripts

/usr/local/bin contains three helpful scripts. To run them, start LXTerminal (in the accessories menu) and simply enter the commands as demonstrated below. They are in all users' paths, so may be executed from any working directory.

Update web2py

Enter the command with or without a revision number, as demonstrated below: 

update_web2py 2717 # updates web2py to revision 2717
update_web2py # updates web2py to current revision

Update Eden

update_eden 1560 # updates Eden to revision 1560
update_eden # updates Eden to current revision

Web2Py shell

launch a Web2py shell in the Eden environment 

import_eden

NB Script seems oddly named

Troubleshooting older Releases

Note: If you get a ticket when running the application for the 1st time with a message like "OperationalError: Cannot add a UNIQUE column" then you need to stop the debugger, delete the contents of the databases folder & then start debugging again (there was an old database accidentally left on the system which cannot be auto-migrated - a new image without this issue has been uploaded): 

rm -rf ~/Desktop/web2py/applications/eden/databases/*

If you get an error like "AttributeError: SQLCustomType instance has no attribute 'startswith'" then: 

cd ~/Desktop/web2py/gluon
rm sql.py
wget http://eden.sahanafoundation.org/sql.py

Then can proceed as above: Stop Eclipse, empty databases folder & restart Eclipse

A new image without this issue has now been uploaded.

Procedure for making a new virtual machine image:

InstallationGuidelinesVirtualMachineMaintenance

Note: See TracWiki for help on using the wiki.