Live GIS Build

=About=

GISVM is an Xubuntu based Virtual Machine which has been installed with a suite of the best Open Source Geospatial software. It is also used to build Arramagong, the Linux based Live DVD.

=How to add your project or data to GISVM / Arramagong=

All that's required to add your favorite package into GISVM is to:


 * Optional: Subscribe to the Live Demo email list to discuss issues.


 * Optional: Install the latest Arramamgong / GIS virtual machine to download into. (Alternatively, you may be able to get away with just using an Xubuntu or Ubuntu installation you may already have.)
 * Download the latest Arramagong / GISVM virtual machine from: http://download.osgeo.org/livedvd
 * On 1 Sept 2009, this is Arramagong_GISVM_FOSS4G2009_alpha, which is 2.3 Gig, compressed with 7 Zip, and needs to be downloaded in 4 parts, then added back together using 7 Zip.
 * On linux: assuming all 4 files are stored in the same folder, use a console to go to that folder and type:
 * This will extract all four files automaticaly. You get 2 files named  and
 * This will extract all four files automaticaly. You get 2 files named  and


 * Install into a Virtual Machine. We recommend using VMWare, but VirtualBox works also.
 * VirutalBox - Open the Virtual Disk Manager and add a harddisk, point it to the vmdk file and save. Now create a new machine and when prompted select the existing vmdk as the disk. It shouldn't ask you for anything else other than ram allocation, name and OS type.


 * write a shell script which installs and configures your stable package into the current GISVM virtual machine (which will usually be the same as installing on Xubuntu or Ubuntu).


 * add the script to subversion, in https://svn.osgeo.org/osgeo/livedvd/gisvm/trunk/bin/, as per http://wiki.osgeo.org/wiki/Live_GIS_Disc#Subversion
 * If you do not have write permission there feel free to send the script to the OSGeo live-demo mailing list as an attachment and we'll see that it makes it in.


 * Notify the GISVM team to test your script, and will ensure to reference your script from main.sh.

Example scripts
You can see example scripts at: https://svn.osgeo.org/osgeo/livedvd/gisvm/trunk/bin/

The script may be as simple as:

install_mapserver.sh, which just "apt-get install mapserver"

Projects that haven't been packaged yet are slightly more complicated:

The Udig package is a good example: install_udig.sh

wget https://svn.osgeo.org/osgeo/livedvd/gisvm/trunk/sources.list.d/qgis.list --output-document=/etc/apt/sources.list.d/qgis.list don't forget to add the repository key like so apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 68436DDF
 * 3rd Party Repositories - Create an .list file with your repository in sources.list.d/ in the svn, in your script copy the file to the local machine like

Packaging conventions
echo "install_ .sh FIXME:
 * 1) Assume the script is to be executed as root.
 * 2) It is ok initially to have manual steps in your script. When this happens, include:
 * 3) FIXME
 * 1) Where appropriate, create an icon on the desktop which loads the application.  (Todo: How do we do this?)
 * 2) Create an icon in the the Applications pull down list. (Todo: How do we do this?)
 * 3) If the application is launched from the browser, then include the application in Firefox bookmarks.

= Build Drivers =

Which version?
The criteria used to select applications for GISVM is as follows:


 * 1) Priority goes to Ubuntu packaged software first, then Debian packaged software! This facilitates easy and reliable maintenance and update. Users will benefit from it. Programmers are encouraged to move their software into DebianGIS or UbuntuGIS repositories.
 * 2) Stable, always! GISVM users are mainly starters. So they obviously are better with stable software. They have enough problems already and will gladly be happier without software bugs.

For people who want the latest version, they can create an alternative upgrade script.

Low Memory
Both Virtual Machines, and a LiveDVD images are likely to be constrained by limited memory. So to reduce memory usage. Disk image size is not of major concern, as we can just distribute less data.

The following principles should be followed.
 * 1) Do not start applications upon power up. (Ie, don't start deamons, allow users to start them instead).
 * 2) Set up examples which, by default, don't depend on other applications. Less applications open, means less memory. Ie, Have GeoServer access a shapefile instead of PostGIS.
 * 3) Try to avoid scenarios which write data to disk, as disk space in the Live DVD is stored in RAM, and is not cleared afterward.

= Directory Structure =


 * 1) /tmp Temporary files (e.g., downloaded archives) go into /tmp. Please create a separate folder for your project.
 * 2) /usr/lib application are usually installed into /usr/lib
 * 3) /usr/bin things that get executed by the user such as startup scripts or links to them should go into /usr/bin
 * 4) /etc/init.d startup/shutdown scripts for services (e.g., postgres, apache, tomcat) are stored in /etc/init.d
 * 5) /usr/local/share sample data and documentation goes into /usr/local/share
 * 6) /etc config files are stored in /etc
 * 7) /home/user user specific config files or working directories can go into /home/user/. However, keep files in /home/user as small as possible as this folder is loaded into memory in the Live DVD. Symlinks into /usr/local can be useful here.

= Mounting as Existing Image = For the purposes of faster dissemination of updates to the Live image via something like rsync you can mount an image file. Make sure you turn off the virtual machine before you attempt to mount it, and that you unmount it before you attempt to run the vm again.

Using VMWare
This method assumes you have vmware server installed, the key is that the vmware-mount script is on your system somewhere. This instructions use /space/virtual as the vmware installation folder and /space/virtual/machines as the location of the disk images. For more information see the VMware mounting guide sudo ln -s /space/virtual/lib/vmware/ libdir sudo ./vmware-mount -p /space/virtual/machines/gisvm20090828x.vmdk mkdir /space/virtual/machines sudo ./vmware-mount /space/virtual/machines/gisvm20090828x.vmdk 1 /space/virtual/machines/mountedimage sudo ./vmware-mount -d /space/virtual/machines/mountedimage
 * If it complains about not finding libdir/lib/libcrypto.so.0.9.8/libcrypto.so.0.9.8
 * It's because it's looking for it in your vmware bin/libdir which doesn't exist so symlink
 * Temporarily move your .vmx file out of the directory
 * Should be partition 1
 * Make a directory to mount to somewhere easy to find, in my case where I keep my vm images
 * Mount it
 * Don't forget to umount when you're done

Using VirtualBox
These instructions have not been tested yet, they require VirtualBox 2.0+ http://forums.virtualbox.org/viewtopic.php?f=7&t=17574

= Creating a fresh Virtual Machine = If you want to start from scratch and build your own custom virtual machine. Take a look at vmbuilder on Ubuntu apt-get install python-vm-builder