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`_ to allow 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 (amd64)
  28   <http://neuro.debian.net/debian/vm/neurodebian_6.0.0_amd64.zip>`_ [~570MB]
  29 * `VirtualBox download page <http://www.virtualbox.org/wiki/Downloads>`_ (Windows, Linux, Mac,
  30   Solaris)
  31
  32 Installation
  33 ------------
  34
  35 First download and install a recent version of VirtualBox_. VirtualBox is a
  36 virtualization software that is freely available for Windows, MacOS X, Solaris,
  37 and Linux. VirtualBox comes with a comprehensive manual that should answer
  38 potential questions regarding installation and maintenance.
  39
  40 .. _VirtualBox: http://www.virtualbox.org
  41
  42 Next, download the most recent version of the NeuroDebian virtual machine from
  43 the `download page`_ (about 1GB download size). The machine is distributed as a
  44 `tar` file. Please extract this file, using appropriate software for your
  45 operating system. Every Linux system comes with the `tar` commandline utility,
  46 and potentially other graphical archivers that can extract this format. MacOS X
  47 users can simply double-click such file to extract it. Windows users can extract
  48 it with, for example, 7zip_.
  49
  50 Once extracted, you'll find a directory with three files. Now start VirtualBox,
  51 and select "Import Appliance" from the file menu.
  52
  53 .. _download page: http://neuro.debian.net/debian/vm
  54 .. _7zip: http://www.7-zip.org/
  55
  56 .. image:: pics/vm_import_app.jpg
  57
  58 Next dialog will ask you to choose a virtual machine. Please navigate to the
  59 extracted NeuroDebian download and select the `NeuroDebian.ovf` file.
  60
  61 .. image:: pics/vm_import_wizard.jpg
  62
  63 You can finish importing of NeuroDebian by clicking on *next* a couple of times. There
  64 is no need to change anything, as we will get through the settings in a second.
  65 Importing of the virtual machine will take a short while, as it is distributed in
  66 a compressed format that now gets extracted (total extracted size about 3.5
  67 GB).  Once imported, the NeuroDebian virtual machine will appear in the list of
  68 available machines. Do **not** start it yet, but select NeuroDebian and hit the
  69 *Settings* button. In the following dialog you'll have a chance to configure
  70 the machine. You can assign the amount of RAM that should be made available to
  71 it (for serious fMRI data processing, please allow at least 2 GB). If you have
  72 a recent computer with multiple CPU cores, you can also decide how many cores
  73 should be used by the virtual machine. If you have a large screen you should
  74 increase the display memory to 32 MB in the *Display* settings.
  75
  76 .. image:: pics/vm_add_host_folder.jpg
  77
  78 However, most important is the *Shared Folders* setup. Shared folders allow the
  79 virtual machine to access the local harddrive of the host computer. This is an
  80 easy way to access data on the computer without duplicating it or using the
  81 network to access it. The virtual machine is preconfigured to access a shared folder named
  82 labeled "host".  Click on the *add* button to select a folder that shall be
  83 accessible by the machine (e.g. your home directory) and put "host" as the
  84 folder name. Note, the folder name is simply a label. Your directory will not
  85 be renamed.
  86
  87 .. image:: pics/vm_host_folder.jpg
  88
  89 Finally, close the settings dialog. You have now completed the setup, and you
  90 can start the virtual machine by hitting the *Start* button. A new window will
  91 appear showing the boot process. After a short while the NeuroDebian desktop
  92 will appear. You can now explore the system. The virtual machine is connected
  93 with your host computer, and shares its Internet connection. Via this
  94 connection you can update the contained software packages at any time.
  95
  96 .. warning::
  97
  98   VirtualBox might offer you to upgrade the "guest additions" to version 3.1.2.
  99   Do **not** do this, since that version is broken, and after the upgrade you
 100   will now longer be able to use the mouse inside the virtual machine.
 101
 102 .. image:: pics/vm_settings.jpg
 103
 104 The virtual machine logs yourself in automatically. The name of the virtual
 105 machine user is `brain` and the password is `neurodebian`. The *root* password
 106 is also `neurodebian`. In most cases, however, you should not be forced to type
 107 the password, since `sudo` is configured to work without it.
 108
 109 Enjoy!
 110
 111
 112
 113 Details
 114 -------
 115
 116 The virtual machine contains an installation of `Debian 5.0 (lenny)`_ with a
 117 GNOME_ desktop environment. All installed software comes from standard Debian
 118 packages, or prospective Debian packages from NeuroDebian -- no custom
 119 installations whatsoever. This means that all contained software is readily
 120 available for any system running a Debian operating system (or a recent Ubuntu
 121 release). The virtual machine can be seen as a showcase of what Debian for
 122 neuroscience research feels like. Moreover, once downloaded this virtual
 123 machine can be kept up to date, just as any other Debian installation. Using
 124 convenient graphical package management tools users will benefit from security
 125 bugfixes provided by the Debian project for the whole operating system, as well
 126 as from software updates for neuroscience-related packages.
 127
 128 .. _Debian 5.0 (lenny): http://www.debian.org/releases/stable
 129 .. _GNOME: http://www.gnome.org/
 130
 131
 132
 133 Troubleshooting
 134 ---------------
 135
 136 There is no network connectivity.
 137
 138   If the virtual machine cannot access the internet, but the host computer can,
 139   it might be necessary to re-establish the network connection. To do this,
 140   please click on the `network manager` icon in the virtual machine's system
 141   tray (upper right corner of the desktop) and select `Wired Network`. After a
 142   few seconds the network should become available.
 143
 144
 145 I cannot hear sounds played in the virtual machine.
 146
 147   Sorry, but audio is not (yet) preconfigured properly. If you want to have that
 148   fixed, please drop us a note.