NeuroDebian Virtual Machine
===========================
-Those, who are not yet running a Debian-based operating system, but are already
-tired of fiddling with dozens of neuro-software packages, can get a glimpse of
-neuroscience research in a Debian environment via a `virtual machine`_.
+.. quotes::
+ :random: 1
+ :tags: vm
+
+For those who are not yet running a Debian-based operation system we offer a
+`virtual machine`_ that can be used with `VirtualBox`_, allowing users to benefit
+from a Debian-based research environment on other operating systems.
+This virtual machine initially comes as a compact Debian installation that can,
+once installed, be equipped with a large variety of neuroscience software with
+just a few mouse clicks (e.g. AFNI_, Caret_, FSL_, PyMVPA_).
.. _virtual machine: http://en.wikipedia.org/wiki/Virtual_machine
-NeuroDebian offers a virtual machine that comes preinstalled with a number
-of popular neuroscience packages (e.g. AFNI_, Caret_, FSL_, PyMVPA_).
-.. _AFNI: http://afni.nimh.nih.gov/afni/
-.. _Caret: http://brainvis.wustl.edu/wiki/index.php/Caret:About
-.. _FSL: http://www.fmrib.ox.ac.uk/fsl/
-.. _PyMVPA: http://www.pymvpa.org
+Downloads
+---------
+
+Stable (6.x series)
+~~~~~~~~~~~~~~~~~~~
+
+Based on current stable `Debian 6.0 (squeeze)`_ release. This VM
+provides a stable, well tested environment with the most of the recent
+releases available from NeuroDebian.
+
+* `NeuroDebian 6.0.6 image (32bit)
+ <http://neuro.debian.net/debian/vm/NeuroDebian_6.0.6_i386.ova>`_ [~559MB]
+
+ *This image should work on virtually all systems that are supported by*
+ VirtualBox_ *and can be used whenever the, otherwise preferable, 64bit image
+ is not compatible with a host machine.*
+
+* `NeuroDebian 6.0.6 image (64bit)
+ <http://neuro.debian.net/debian/vm/NeuroDebian_6.0.6_amd64.ova>`_ [~576MB]
+
+ *This image only works on 64bit host machines with active hardware
+ virtualization support. The should include all recent Apple hardware and most
+ 64bit Windows systems.*
+
+Development (to be 7.x series)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Based on upcoming `Debian 7.0 (wheezy)`_ release. Although already
+quite stable, there might be outstanding issues. This VM also
+switches from GNOME_ (v.2) desktop environment to XFCE4_. We
+recommend this VM over a stable one for anyone needing recent releases
+of tools not available for the stable VM (e.g. recent pandas) --
+**getting a complete "Scientific Python" stack with 100s of other
+Python modules was never easier**. Moreover your feedback might also
+be valuable to polish upcoming Debian wheezy release and NeuroDebian
+VM 7.0.
+
+* `NeuroDebian 6.999.b4.20121231 image (32bit)
+ <http://neuro.debian.net/debian/vm/NeuroDebian_6.999.b4.20121231_i386.ova>`_ [~656MB]
+
+* `NeuroDebian 6.999.b4.20121231 image (64bit)
+ <http://neuro.debian.net/debian/vm/NeuroDebian_6.999.b4.20121231_amd64.ova>`_ [~660MB]
+
+
+Historical
+~~~~~~~~~~
+
+Virtual appliances above carry guest additions for 4.x series of the
+VirtualBox. If you still have VirtualBox 3.x, use previous 6.0.2
+virtual appliances:
+
+* `NeuroDebian 6.0.2 image (32bit)
+ <http://neuro.debian.net/debian/vm/neurodebian_6.0.2_i386.zip>`_ [~545MB]
+
+* `NeuroDebian 6.0.2 image (64bit)
+ <http://neuro.debian.net/debian/vm/neurodebian_6.0.2_amd64.zip>`_ [~560MB]
+
+.. note::
+
+ This older virtual appliances are distributed as a `zip` file. Please
+ extract all files from the `.zip` file, using appropriate software
+ for your operating system.
+
+.. note::
+
+ You can verify that you have downloaded archives correctly using
+ `md5sums -c MD5SUMS
+ <http://neuro.debian.net/debian/vm/MD5SUMS>`_ . You can also verify
+ the authenticity of the `MD5SUMS
+ <http://neuro.debian.net/debian/vm/MD5SUMS>`_ itself using `gpg
+ --verify MD5SUMS.gpg
+ <http://neuro.debian.net/debian/vm/MD5SUMS.gpg>`_ signed with
+ NeuroDebian archive key.
+
+* `VirtualBox download page <http://www.virtualbox.org/wiki/Downloads>`_ (Windows, Linux, Mac,
+ Solaris)
+
+ *This webpage offers installers of the VirtualBox application, as well as the
+ documentation.*
+
+Changes
+-------
+
+6.999.b4.20121231 -- 31 Dec 2012
+
+ * Based on beta 4 release of debian-installer_ for wheezy
+ * Comes with XFCE4_ instead of GNOME_
+
+6.0.6 -- 01 Oct 2012
+
+ * Updated core system to Debian squeeze 6.0.6
+
+6.0.5 -- 10 Nov 2011
+
+ * Updated core system to Debian squeeze 6.0.3
+ * Updated shipped virtualbox-ose guest-utils and guest-x11 to 4.0.10
+
+ - ``~/host`` is now symlinked to correct path ``/media/sf_host``
+ - ``brain`` user is added to ``vboxsf`` group so mounted host
+ directories should become readily available
+
+ * Root partition size and swap space got doubled in size (40GB
+ and 2GB correspondingly). Space is allocated dynamically so
+ the actual size of the virtual drive should not grow unless
+ you use it
-The virtual machine contains an installation of `Debian 5.0 (lenny)`_ with a
+6.0.4 -- 13 Jun 2011
+
+ * Updated shipped virtualbox-ose guest-utils and guest-x11 to 4.0.4
+
+6.0.3 -- 12 Jun 2011 [Superseded in the archive by 6.0.4]
+
+ * Updated to Debian squeeze 6.0.1
+ * Updated VirtualBox guest additions to 4.0.4 from backports.debian.org
+ * Appliance is available as a single file (.ova) ready for the import
+
+6.0.2 -- 08 Feb 2011
+
+6.0.1 -- 01 Dec 2010
+
+Documentation
+-------------
+
+The virtual machine contains an installation of `Debian 6.0 (squeeze)`_ with a
GNOME_ desktop environment. All installed software comes from standard Debian
-packages, or prospective Debian packages from NeuroDebian -- no custom
-installations whatsoever. This means that all contained software is readily
-available for any system running a Debian operating system (or a recent Ubuntu
-release). The virtual machine can be seen as a showcase of what Debian for
-neuroscience research feels like. Moreover, once downloaded this virtual
-machine can be kept up to date, just as any other Debian installation. Using
-convenient graphical package management tools users will benefit from security
-bugfixes provided by the Debian project for the whole operating system, as well
-as from software updates for neuroscience-related packages.
+packages, or prospective Debian packages from NeuroDebian. This means that all
+contained software is readily available for any system running a Debian
+operating system (or a recent Ubuntu release). The virtual machine can be seen
+as a showcase of what Debian for neuroscience research feels like. Moreover,
+once downloaded this virtual machine can be kept up to date, just as any other
+Debian installation. Using convenient graphical package management tools users
+will benefit from security bug fixes provided by the Debian project for the
+whole operating system, as well as from software updates for
+neuroscience-related packages.
-.. _Debian 5.0 (lenny): http://www.debian.org/releases/stable
-.. _GNOME: http://www.gnome.org/
Installation
-------------
+~~~~~~~~~~~~
+
+The following video shows how to get the NeuroDebian virtual machine running
+on your machine. The installation is shown for Mac OS X. It should, however, be
+very similar on a Windows box. If you cannot watch the video, please take a
+look at the written instructions below.
+
+.. raw:: html
+
+ <iframe title="YouTube video player"
+ class="youtube-player"
+ type="text/html"
+ width="640"
+ height="375"
+ src="http://www.youtube.com/embed/eqfjKV5XaTE?hd=1"
+ frameborder="0"></iframe>
First download and install a recent version of VirtualBox_. VirtualBox is a
virtualization software that is freely available for Windows, MacOS X, Solaris,
.. _VirtualBox: http://www.virtualbox.org
Next, download the most recent version of the NeuroDebian virtual machine from
-the `download page`_ (about 1GB download size). The machine is distributed as a
-`tar` file. Please extract this file, using appropriate software for your
-operating system. Every Linux system comes with the `tar` commandline utility,
-and potentially other graphical archivers that can extract this format. MacOS X
-users can simply double-click such file to extract it. Windows users can extract
-it with, for example, 7zip_.
-
-Once extracted, you'll find a directory with three files. Now start VirtualBox,
-and select "Import Appliance" from the file menu.
-
-.. _download page: http://neuro.debian.net/debian/vm
-.. _7zip: http://www.7-zip.org/
+the Downloads_ section. Start VirtualBox and select "Import Appliance" from the file
+menu.
.. image:: pics/vm_import_app.jpg
-Next dialog will ask you to choose a virtual machine. Please navigate to the
-extracted NeuroDebian download and select the `NeuroDebian.ovf` file.
+The next dialog will ask you to choose a virtual machine. Please navigate to the
+extracted NeuroDebian download and select the `.ova` (or extracted
+`.ovf` for older appliances shipped as `.zip`) file.
.. image:: pics/vm_import_wizard.jpg
-You can finish importing of NeuroDebian by clicking on *next* a couple of times. There
-is no need to change anything, as we will get through the settings in a second.
-Importing of the virtual machine will take a short while, as it is distributed in
-a compressed format that now gets extracted (total extracted size about 3.5
-GB). Once imported, the NeuroDebian virtual machine will appear in the list of
-available machines. Do **not** start it yet, but select NeuroDebian and hit the
-*Settings* button. In the following dialog you'll have a chance to configure
-the machine. You can assign the amount of RAM that should be made available to
-it (for serious fMRI data processing, please allow at least 2 GB). If you have
-a recent computer with multiple CPU cores, you can also decide how many cores
-should be used by the virtual machine. If you have a large screen you should
-increase the display memory to 32 MB in the *Display* settings.
+You can finish importing of NeuroDebian by clicking on *next* a couple of
+times. There is no need to change anything, as we will get through the
+settings in a second. Importing of the virtual machine will take a short
+while, as it is distributed in a compressed format that now gets extracted
+(total extracted size about 2 GB). Once imported, the NeuroDebian virtual
+machine will appear in the list of available machines. Do **not** start it yet,
+but select NeuroDebian and hit the *Settings* button. In the following dialog
+you'll have a chance to configure the machine. You can assign the amount of RAM
+that should be made available to it (for serious fMRI data processing, please
+allow at least 2 GB). If you have a recent computer with multiple CPU cores,
+you can also decide how many cores should be used by the virtual machine.
.. image:: pics/vm_add_host_folder.jpg
However, most important is the *Shared Folders* setup. Shared folders allow the
virtual machine to access the local harddrive of the host computer. This is an
easy way to access data on the computer without duplicating it or using the
-network to access it. The virtual machine is preconfigured to access a shared folder named
-labeled "host". Click on the *add* button to select a folder that shall be
-accessible by the machine (e.g. your home directory) and put "host" as the
-folder name. Note, the folder name is simply a label. Your directory will not
-be renamed.
+network to access it. The virtual machine is preconfigured to access a shared
+folder named labeled "host". Click on the *add* button to select a folder that
+shall be accessible by the machine (e.g. your home directory) and put "host" as
+the folder name and mark it to be auto-mounted. Note, the folder name is simply a label. Your directory will
+not be renamed.
.. image:: pics/vm_host_folder.jpg
+If you have a large screen you should increase the display memory to
+32 MB in the *Display* settings. Also you might like to enable the
+support for 3D Acceleration
+
+.. image:: pics/vm_settings_display.jpg
+
Finally, close the settings dialog. You have now completed the setup, and you
can start the virtual machine by hitting the *Start* button. A new window will
appear showing the boot process. After a short while the NeuroDebian desktop
-will appear. You can now explore the system. The virtual machine is connected
+will appear, and a setup wizard will guide your through the final steps of the
+configuration. You can now explore the system. The virtual machine is connected
with your host computer, and shares its Internet connection. Via this
connection you can update the contained software packages at any time.
-.. warning::
-
- VirtualBox might offer you to upgrade the "guest additions" to version 3.1.2.
- Do **not** do this, since that version is broken, and after the upgrade you
- will now longer be able to use the mouse inside the virtual machine.
-
.. image:: pics/vm_settings.jpg
The virtual machine logs yourself in automatically. The name of the virtual
is also `neurodebian`. In most cases, however, you should not be forced to type
the password, since `sudo` is configured to work without it.
-Enjoy!
+.. note::
+ For increased security you might want to change the default password. You can
+ do so by opening a terminal window and running the ``passwd`` command.
+
+
+Working with the virtual machine
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The next video is a demonstration of some basic desktop integration features.
+It shows how to use the virtual machine in full-screen and seamless mode, shared
+folder access, software installation, as well as suspending and resuming the
+virtual machine.
+
+.. raw:: html
+
+ <iframe title="YouTube video player"
+ class="youtube-player"
+ type="text/html"
+ width="640"
+ height="375"
+ src="http://www.youtube.com/embed/OV7fYSEoOeQ?hd=1"
+ frameborder="0"></iframe>
+
+
+.. _chap_vm_troubleshooting:
Troubleshooting
----------------
+~~~~~~~~~~~~~~~
+
+Updating the VM or installing new packages doesn't work.
-There is no network connectivity.
+ The VM uses as service that tries to figure out the best/closest package
+ repository for you. In some network environments this service might not work
+ well, or not at all. To check if this is a problem, you can modify the
+ respective configuration by hand. Edit ``/etc/apt/sources.list`` (you need to
+ use ``sudo`` for that) and replace the package repository URL with a mirror
+ close to you. A comprehensive list of mirrors is available at:
+ http://www.debian.org/mirror/list
- If the virtual machine cannot access the internet, but the host computer can,
- it might be necessary to re-establish the network connection. To do this,
- please click on the `network manager` icon in the virtual machine's system
- tray (upper right corner of the desktop) and select `Wired Network`. After a
- few seconds the network should become available.
+ Pick one and replace all ``geomirror.debian.net`` URLs with the new mirror
+ URL. For example, in Canada you might want to change::
+ deb http://i386-geomirror.debian.net/debian squeeze main non-free contrib
+
+ to::
+
+ deb http://ftp.ca.debian.org/debian/ squeeze main non-free contrib
+
+ Only modify lines that refer to ``geomirror`` (all of them), but do **not**
+ modify entries for ``security.debian.org``.
I cannot hear sounds played in the virtual machine.
- Sorry, but audio is not (yet) preconfigured properly. If you want to have that
- fixed, please drop us a note.
+ By default the sound is muted. To enable playback launch the mixer applet by
+ clicking on the mixer icon in the task bar. Unmute the master volume control.
+ Now click on the "Volume control" to load the channel mixer dialog. Unmute
+ the "Master" and "PCM" channels and raise the volume as desired. You should
+ now be able to hear sounds played within the virtual machines through your
+ host computer's speakers.
+
+I have upgraded VirtualBox from 3.x series to 4.x, and my VM lost
+mounted host directories.
+
+ NeuroDebian VMs prior 6.0.3 were shipped with guest additions from
+ 3.x series of VirtualBox and some initial versions of VirtualBox in
+ 4.x series have failed to mount host directories properly.
+ VirtualBox 4.0.8 seems to work fine with guest additions from 3.x
+ series. If you nevertheless want to upgrade guest additions within
+ NeuroDebian VM, please rebuild the version available from the
+ backports::
+
+ sudo apt-get install -y linux-headers-2.6-amd64 # or -686 for 32bit
+ sudo apt-get install -y -t squeeze-backports virtualbox-ose-guest-dkms \
+ virtualbox-ose-guest-utils virtualbox-ose-guest-x11
+
+ and reboot VM.
+.. include:: link_names.txt
projects / neurodebian.git / blobdiff