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.0 image (32bit) [coming soon; leave a comment below if you
  28   need it urgently]
  29 * `NeuroDebian 6.0.0 image (64bit)
  30   <http://neuro.debian.net/debian/vm/neurodebian_6.0.0_amd64.zip>`_ [~570MB]
  31 * `VirtualBox download page <http://www.virtualbox.org/wiki/Downloads>`_ (Windows, Linux, Mac,
  32   Solaris)
  33
  34
  35 Documentation
  36 -------------
  37
  38 The virtual machine contains an installation of `Debian 6.0 (squeeze)`_ with a
  39 GNOME_ desktop environment. All installed software comes from standard Debian
  40 packages, or prospective Debian packages from NeuroDebian. This means that all
  41 contained software is readily available for any system running a Debian
  42 operating system (or a recent Ubuntu release). The virtual machine can be seen
  43 as a showcase of what Debian for neuroscience research feels like. Moreover,
  44 once downloaded this virtual machine can be kept up to date, just as any other
  45 Debian installation. Using convenient graphical package management tools users
  46 will benefit from security bug fixes provided by the Debian project for the
  47 whole operating system, as well as from software updates for
  48 neuroscience-related packages.
  49
  50 .. _Debian 6.0 (squeeze): http://www.debian.org/releases/squeeze
  51 .. _GNOME: http://www.gnome.org/
  52
  53
  54 Installation
  55 ~~~~~~~~~~~~
  56
  57 The following video shows how to get the NeuroDebian virtual machine running
  58 on your machine. The installation is shown for Mac OS X. It should, however, be
  59 very similar on a Windows box. If you cannot watch the video, please take a
  60 look at the written instructions below.
  61
  62 .. raw:: html
  63
  64   <iframe title="YouTube video player"
  65           class="youtube-player"
  66           type="text/html"
  67           width="640"
  68           height="375"
  69           src="http://www.youtube.com/embed/eqfjKV5XaTE?hd=1"
  70           frameborder="0"></iframe>
  71
  72 First download and install a recent version of VirtualBox_. VirtualBox is a
  73 virtualization software that is freely available for Windows, MacOS X, Solaris,
  74 and Linux. VirtualBox comes with a comprehensive manual that should answer
  75 potential questions regarding installation and maintenance.
  76
  77 .. _VirtualBox: http://www.virtualbox.org
  78
  79 Next, download the most recent version of the NeuroDebian virtual machine from
  80 the Downloads_ section. The machine is distributed as a zip file. Please
  81 extract this file, using appropriate software for your operating system.
  82 Once extracted, start VirtualBox and select "Import Appliance" from the file
  83 menu.
  84
  85 .. image:: pics/vm_import_app.jpg
  86
  87 The next dialog will ask you to choose a virtual machine. Please navigate to the
  88 extracted NeuroDebian download and select the `.ovf` file.
  89
  90 .. image:: pics/vm_import_wizard.jpg
  91
  92 You can finish importing of NeuroDebian by clicking on *next* a couple of
  93 times.  There is no need to change anything, as we will get through the
  94 settings in a second.  Importing of the virtual machine will take a short
  95 while, as it is distributed in a compressed format that now gets extracted
  96 (total extracted size about 2 GB).  Once imported, the NeuroDebian virtual
  97 machine will appear in the list of available machines. Do **not** start it yet,
  98 but select NeuroDebian and hit the *Settings* button. In the following dialog
  99 you'll have a chance to configure the machine. You can assign the amount of RAM
 100 that should be made available to it (for serious fMRI data processing, please
 101 allow at least 2 GB). If you have a recent computer with multiple CPU cores,
 102 you can also decide how many cores should be used by the virtual machine. If
 103 you have a large screen you should increase the display memory to 32 MB in the
 104 *Display* settings.
 105
 106 .. image:: pics/vm_add_host_folder.jpg
 107
 108 However, most important is the *Shared Folders* setup. Shared folders allow the
 109 virtual machine to access the local harddrive of the host computer. This is an
 110 easy way to access data on the computer without duplicating it or using the
 111 network to access it. The virtual machine is preconfigured to access a shared
 112 folder named labeled "host".  Click on the *add* button to select a folder that
 113 shall be accessible by the machine (e.g. your home directory) and put "host" as
 114 the folder name. Note, the folder name is simply a label. Your directory will
 115 not be renamed.
 116
 117 .. image:: pics/vm_host_folder.jpg
 118
 119 Finally, close the settings dialog. You have now completed the setup, and you
 120 can start the virtual machine by hitting the *Start* button. A new window will
 121 appear showing the boot process. After a short while the NeuroDebian desktop
 122 will appear, and a setup wizard will guide your through the final steps of the
 123 configuration. You can now explore the system. The virtual machine is connected
 124 with your host computer, and shares its Internet connection. Via this
 125 connection you can update the contained software packages at any time.
 126
 127 .. image:: pics/vm_settings.jpg
 128
 129 The virtual machine logs yourself in automatically. The name of the virtual
 130 machine user is `brain` and the password is `neurodebian`. The *root* password
 131 is also `neurodebian`. In most cases, however, you should not be forced to type
 132 the password, since `sudo` is configured to work without it.
 133
 134 .. note::
 135
 136   For increased security you might want to change the default password. You can
 137   do so by opening a terminal window and running the ``passwd`` command.
 138
 139
 140 Working with the virtual machine
 141 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 142
 143 The next video is a demonstration of some basic desktop integration features.
 144 It shows how to use the virtual machine in full-screen and seamless mode, shared
 145 folder access, software installation, as well as suspending and resuming the
 146 virtual machine.
 147
 148 .. raw:: html
 149
 150   <iframe title="YouTube video player"
 151           class="youtube-player"
 152           type="text/html"
 153           width="640"
 154           height="375"
 155           src="http://www.youtube.com/embed/OV7fYSEoOeQ?hd=1"
 156           frameborder="0"></iframe>
 157
 158
 159 Troubleshooting
 160 ~~~~~~~~~~~~~~~
 161
 162 I cannot hear sounds played in the virtual machine.
 163
 164   By default the sound is muted. To enable playback launch the mixer applet by
 165   clicking on the mixer icon in the task bar. Unmute the master volume control.
 166   Now click on the "Volume control" to load the channel mixer dialog. Unmute
 167   the "Master" and "PCM" channels and raise the volume as desired. You should
 168   now be able to hear sounds played within the virtual machines through your
 169   host computer's speakers.