sphinx/vm.rst

   1 .. _chap_vm:
   2
   3 NeuroDebian Virtual Machine
   4 ===========================
   5
   6 .. quotes::
   7    :random: 1
   8    :tags: vm
   9
  10 For those who are not yet running a Debian-based operation system we offer a
  11 `virtual machine`_ that can be used with `VirtualBox`_, allowing users to benefit
  12 from a Debian-based research environment on other operating systems.
  13 This virtual machine initially comes as a compact Debian installation that can,
  14 once installed, be equipped with a large variety of neuroscience software with
  15 just a few mouse clicks (e.g. AFNI_, Caret_, FSL_, PyMVPA_).
  16
  17 .. _virtual machine: http://en.wikipedia.org/wiki/Virtual_machine
  18 .. _AFNI: http://afni.nimh.nih.gov/afni/
  19 .. _Caret: http://brainvis.wustl.edu/wiki/index.php/Caret:About
  20 .. _FSL: http://www.fmrib.ox.ac.uk/fsl/
  21 .. _PyMVPA: http://www.pymvpa.org
  22
  23
  24 Downloads
  25 ---------
  26
  27 * `NeuroDebian 6.0.1 image (32bit)
  28   <http://neuro.debian.net/debian/vm/neurodebian_6.0.1_i386.zip>`_ [~560MB]
  29
  30   *This image should work on virtually all systems that are supported by*
  31   VirtualBox_ *and can be used whenever the, otherwise preferable, 64bit image
  32   is not compatible with a host machine.*
  33
  34 * `NeuroDebian 6.0.1 image (64bit)
  35   <http://neuro.debian.net/debian/vm/neurodebian_6.0.1_amd64.zip>`_ [~570MB]
  36
  37   *This image only works on 64bit host machines with active hardware
  38   virtualization support. The should include all recent Apple hardware and most
  39   64bit Windows systems.*
  40
  41 .. note::
  42
  43   You can verify that you have downloaded archives correctly using
  44   `md5sums -c MD5SUMS
  45   <http://neuro.debian.net/debian/vm/MD5SUMS>`_ . You can also verify
  46   the authenticity of the `MD5SUMS
  47   <http://neuro.debian.net/debian/vm/MD5SUMS>`_ itself using `gpg
  48   --verify MD5SUMS.gpg
  49   <http://neuro.debian.net/debian/vm/MD5SUMS.gpg>`_ signed with
  50   NeuroDebian archive key.
  51
  52 * `VirtualBox download page <http://www.virtualbox.org/wiki/Downloads>`_ (Windows, Linux, Mac,
  53   Solaris)
  54
  55   *This webpage offers installers of the VirtualBox application, as well as the
  56   documentation.*
  57
  58
  59 Documentation
  60 -------------
  61
  62 The virtual machine contains an installation of `Debian 6.0 (squeeze)`_ with a
  63 GNOME_ desktop environment. All installed software comes from standard Debian
  64 packages, or prospective Debian packages from NeuroDebian. This means that all
  65 contained software is readily available for any system running a Debian
  66 operating system (or a recent Ubuntu release). The virtual machine can be seen
  67 as a showcase of what Debian for neuroscience research feels like. Moreover,
  68 once downloaded this virtual machine can be kept up to date, just as any other
  69 Debian installation. Using convenient graphical package management tools users
  70 will benefit from security bug fixes provided by the Debian project for the
  71 whole operating system, as well as from software updates for
  72 neuroscience-related packages.
  73
  74 .. _Debian 6.0 (squeeze): http://www.debian.org/releases/squeeze
  75 .. _GNOME: http://www.gnome.org/
  76
  77
  78 Installation
  79 ~~~~~~~~~~~~
  80
  81 The following video shows how to get the NeuroDebian virtual machine running
  82 on your machine. The installation is shown for Mac OS X. It should, however, be
  83 very similar on a Windows box. If you cannot watch the video, please take a
  84 look at the written instructions below.
  85
  86 .. raw:: html
  87
  88   <iframe title="YouTube video player"
  89           class="youtube-player"
  90           type="text/html"
  91           width="640"
  92           height="375"
  93           src="http://www.youtube.com/embed/eqfjKV5XaTE?hd=1"
  94           frameborder="0"></iframe>
  95
  96 First download and install a recent version of VirtualBox_. VirtualBox is a
  97 virtualization software that is freely available for Windows, MacOS X, Solaris,
  98 and Linux. VirtualBox comes with a comprehensive manual that should answer
  99 potential questions regarding installation and maintenance.
 100
 101 .. _VirtualBox: http://www.virtualbox.org
 102
 103 Next, download the most recent version of the NeuroDebian virtual machine from
 104 the Downloads_ section. The machine is distributed as a zip file. Please
 105 extract this file, using appropriate software for your operating system.
 106 Once extracted, start VirtualBox and select "Import Appliance" from the file
 107 menu.
 108
 109 .. image:: pics/vm_import_app.jpg
 110
 111 The next dialog will ask you to choose a virtual machine. Please navigate to the
 112 extracted NeuroDebian download and select the `.ovf` file.
 113
 114 .. image:: pics/vm_import_wizard.jpg
 115
 116 You can finish importing of NeuroDebian by clicking on *next* a couple of
 117 times.  There is no need to change anything, as we will get through the
 118 settings in a second.  Importing of the virtual machine will take a short
 119 while, as it is distributed in a compressed format that now gets extracted
 120 (total extracted size about 2 GB).  Once imported, the NeuroDebian virtual
 121 machine will appear in the list of available machines. Do **not** start it yet,
 122 but select NeuroDebian and hit the *Settings* button. In the following dialog
 123 you'll have a chance to configure the machine. You can assign the amount of RAM
 124 that should be made available to it (for serious fMRI data processing, please
 125 allow at least 2 GB). If you have a recent computer with multiple CPU cores,
 126 you can also decide how many cores should be used by the virtual machine. If
 127 you have a large screen you should increase the display memory to 32 MB in the
 128 *Display* settings.
 129
 130 .. image:: pics/vm_add_host_folder.jpg
 131
 132 However, most important is the *Shared Folders* setup. Shared folders allow the
 133 virtual machine to access the local harddrive of the host computer. This is an
 134 easy way to access data on the computer without duplicating it or using the
 135 network to access it. The virtual machine is preconfigured to access a shared
 136 folder named labeled "host".  Click on the *add* button to select a folder that
 137 shall be accessible by the machine (e.g. your home directory) and put "host" as
 138 the folder name. Note, the folder name is simply a label. Your directory will
 139 not be renamed.
 140
 141 .. image:: pics/vm_host_folder.jpg
 142
 143 Finally, close the settings dialog. You have now completed the setup, and you
 144 can start the virtual machine by hitting the *Start* button. A new window will
 145 appear showing the boot process. After a short while the NeuroDebian desktop
 146 will appear, and a setup wizard will guide your through the final steps of the
 147 configuration. You can now explore the system. The virtual machine is connected
 148 with your host computer, and shares its Internet connection. Via this
 149 connection you can update the contained software packages at any time.
 150
 151 .. image:: pics/vm_settings.jpg
 152
 153 The virtual machine logs yourself in automatically. The name of the virtual
 154 machine user is `brain` and the password is `neurodebian`. The *root* password
 155 is also `neurodebian`. In most cases, however, you should not be forced to type
 156 the password, since `sudo` is configured to work without it.
 157
 158 .. note::
 159
 160   For increased security you might want to change the default password. You can
 161   do so by opening a terminal window and running the ``passwd`` command.
 162
 163
 164 Working with the virtual machine
 165 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 166
 167 The next video is a demonstration of some basic desktop integration features.
 168 It shows how to use the virtual machine in full-screen and seamless mode, shared
 169 folder access, software installation, as well as suspending and resuming the
 170 virtual machine.
 171
 172 .. raw:: html
 173
 174   <iframe title="YouTube video player"
 175           class="youtube-player"
 176           type="text/html"
 177           width="640"
 178           height="375"
 179           src="http://www.youtube.com/embed/OV7fYSEoOeQ?hd=1"
 180           frameborder="0"></iframe>
 181
 182
 183 Troubleshooting
 184 ~~~~~~~~~~~~~~~
 185
 186 I cannot hear sounds played in the virtual machine.
 187
 188   By default the sound is muted. To enable playback launch the mixer applet by
 189   clicking on the mixer icon in the task bar. Unmute the master volume control.
 190   Now click on the "Volume control" to load the channel mixer dialog. Unmute
 191   the "Master" and "PCM" channels and raise the volume as desired. You should
 192   now be able to hear sounds played within the virtual machines through your
 193   host computer's speakers.