]> git.donarmstrong.com Git - neurodebian.git/blob - sphinx/vm.rst
VM: switch to install wheezy-based one by default + note on squeeze-based ones
[neurodebian.git] / sphinx / vm.rst
1 .. _chap_vm:
2
3 NeuroDebian Virtual Machine
4 ===========================
5
6 `Installation`_ | `Working with the virtual machine`_ | `Troubleshooting`_ |
7 `What has changed`_
8
9 .. quotes::
10    :random: 1
11    :tags: vm
12
13 For all systems running a non-Debian-based operation system, such as MS Windows
14 or Mac OS X, we offer a `virtual machine`_ that can be equipped with a large
15 variety of neuroscience software with just a few mouse clicks (e.g. AFNI_,
16 FSL_, PyMVPA_).
17
18 .. _virtual machine: http://en.wikipedia.org/wiki/Virtual_machine
19
20 The virtual machine contains an installation of `Debian 6.0 (squeeze)`_ with a
21 GNOME_ desktop environment. All installed software comes from standard Debian
22 packages, or prospective Debian packages from NeuroDebian. The virtual machine
23 can be seen as a showcase of what Debian for neuroscience research feels like.
24 Once downloaded this virtual machine can be kept up to date, just as any other
25 Debian installation. Using convenient graphical package management tools users
26 will benefit from security bug fixes provided by the Debian project for the
27 whole operating system, as well as from software updates for
28 neuroscience-related packages.
29
30 Even on Debian-based systems this virtual machine is an excellent way to
31 maintain an analysis environment that remains identical throughout the lifetime
32 of a study and that can be archived alongside acquired data and publications.
33 This is a much more practical way than freezing the entire software stack of a
34 whole workstation, where it quickly becomes troublesome to combine the desire
35 for latest research methodology for new studies and the need for stability for
36 ongoing projects.
37
38
39 Installation
40 ~~~~~~~~~~~~
41
42 The following instructions demonstrate how to install the NeuroDebian virtual
43 machine -- here shown exemplary for Mac OS X, but the procedure is virtually
44 identical on a Windows box. There is also a video tutorial at coffee break
45 length. `[Virtual machine setup video tutorial]
46 <http://www.youtube.com/watch?v=eqfjKV5XaTE>`_.
47
48 If you don't have t already, first download and install a recent version of
49 VirtualBox_. VirtualBox is a virtualization software that is freely available
50 for Windows, MacOS X, Solaris, and Linux. VirtualBox comes with a comprehensive
51 manual that should answer potential questions regarding installation and
52 maintenance.
53
54 .. _VirtualBox: http://www.virtualbox.org
55
56 Obtain the most recent version of the NeuroDebian virtual machine by visiting
57 http://neuro.debian.net and selecting your operating system and a download
58 server on the frontpage.
59
60 Start VirtualBox and select "Import Appliance" from the file menu.
61
62 .. image:: pics/vm_import_app.jpg
63
64 The next dialog will ask you to choose a virtual machine. Please navigate to the
65 extracted NeuroDebian download and select the `.ova` (or extracted
66 `.ovf` for older appliances shipped as `.zip`) file.
67
68 .. image:: pics/vm_import_wizard.jpg
69
70 You can finish importing of NeuroDebian by clicking on *next* a couple of
71 times.  There is no need to change anything, as we will get through the
72 settings in a second.  Importing of the virtual machine will take a short
73 while, as it is distributed in a compressed format that now gets extracted
74 (total extracted size about 2 GB).  Once imported, the NeuroDebian virtual
75 machine will appear in the list of available machines. Do **not** start it yet,
76 but select NeuroDebian and hit the *Settings* button. In the following dialog
77 you'll have a chance to configure the machine. You can assign the amount of RAM
78 that should be made available to it (for serious fMRI data processing, please
79 allow at least 2 GB). If you have a recent computer with multiple CPU cores,
80 you can also decide how many cores should be used by the virtual machine.
81
82 .. image:: pics/vm_add_host_folder.jpg
83
84 However, most important is the *Shared Folders* setup. Shared folders allow the
85 virtual machine to access the local harddrive of the host computer. This is an
86 easy way to access data on the computer without duplicating it or using the
87 network to access it. The virtual machine is preconfigured to access a shared
88 folder named labeled "host".  Click on the *add* button to select a folder that
89 shall be accessible by the machine (e.g. your home directory) and put "host" as
90 the folder name and mark it to be auto-mounted. Note, the folder name is simply a label. Your directory will
91 not be renamed.
92
93 .. image:: pics/vm_host_folder.jpg
94
95 If you have a large screen you should increase the display memory to
96 32 MB in the *Display* settings.  Also you might like to enable the
97 support for 3D Acceleration
98
99 .. image:: pics/vm_settings_display.jpg
100
101 Finally, close the settings dialog. You have now completed the setup, and you
102 can start the virtual machine by hitting the *Start* button. A new window will
103 appear showing the boot process. After a short while the NeuroDebian desktop
104 will appear, and a setup wizard will guide your through the final steps of the
105 configuration. You can now explore the system. The virtual machine is connected
106 with your host computer, and shares its Internet connection. Via this
107 connection you can update the contained software packages at any time.
108
109 .. image:: pics/vm_settings.jpg
110
111 The virtual machine logs yourself in automatically. This is the default account:
112
113 :user: brain
114 :password: neurodebian
115
116 :root password: neurodebian
117
118 In most cases you should not be forced to type the password, because ``sudo``
119 is configured to work without it.
120
121 .. note::
122
123   For increased security you might want to change the default password. You can
124   do so by opening a terminal window and running the ``passwd`` command.
125
126
127 Working with the virtual machine
128 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
129
130 The NeuroDebian virtual machine has very low maintenance demands. We have
131 prepared a short video demo that shows most typical procedures that you will
132 probably perform while working with NeuroDebian inside a virtual machine:
133 use the virtual machine in full-screen and seamless mode, shared folder access,
134 software installation, as well as suspending and resuming the
135 virtual machine. `[Virtual machine handling video tutorial]
136 <http://www.youtube.com/watch?v=OV7fYSEoOeQ>`_
137
138
139 .. _chap_vm_troubleshooting:
140
141 Troubleshooting
142 ~~~~~~~~~~~~~~~
143
144 .. container:: foldup
145
146   .. container:: expandinstructions
147
148      Click on an item to expand it
149
150   Updating the VM or installing new packages doesn't work
151     The VM uses as service that tries to figure out the best/closest package
152     repository for you. In some network environments this service might not work
153     well, or not at all. To check if this is a problem, you can modify the
154     respective configuration by hand. Edit ``/etc/apt/sources.list`` (you need
155     to use ``sudo`` for that) and replace the package repository URL with a
156     mirror close to you. A comprehensive list of mirrors is available at:
157     http://www.debian.org/mirror/list
158
159     Pick one and replace all ``geomirror.debian.net`` URLs with the new mirror
160     URL. For example, in Canada you might want to change::
161
162       deb http://i386-geomirror.debian.net/debian squeeze main non-free contrib
163
164     to::
165
166       deb http://ftp.ca.debian.org/debian/ squeeze main non-free contrib
167
168     Only modify lines that refer to ``geomirror`` (all of them), but do **not**
169     modify entries for ``security.debian.org``.
170
171   Our proxy setup at work prevents APT from downloading packages
172     APT needs to be told how to access the proxy. Talk to your local sysadmin
173     and ask for the proxy's address (maybe a username and password too), as well
174     as the ports for HTTP and FTP proxies. With this information add the
175     following lines in the file, /etc/apt/apt.conf.d/80proxy. This will ensure
176     that after an upgrade changes won't be lost::
177
178       Acquire::http::proxy "http://<username>:<password>@<proxy>:<port>/";
179       Acquire::ftp::proxy "ftp://<username>:<password>@<proxy>:<port>/";
180       Acquire::https::proxy "https://<username>:<password>@<proxy>:<port>/";
181
182   I cannot hear sounds played in the virtual machine
183     By default the sound is muted. To enable playback launch the mixer applet by
184     clicking on the mixer icon in the task bar. Unmute the master volume
185     control. Now click on the "Volume control" to load the channel mixer dialog.
186     Unmute the "Master" and "PCM" channels and raise the volume as desired. You
187     should now be able to hear sounds played within the virtual machines through
188     your host computer's speakers.
189
190   My VM lost mounted host directories after upgrading from VirtualBox from 3.x to 4.x
191     NeuroDebian VMs prior 6.0.3 were shipped with guest additions from
192     3.x series of VirtualBox and some initial versions of VirtualBox in
193     4.x series have failed to mount host directories properly.
194     VirtualBox 4.0.8 seems to work fine with guest additions from 3.x
195     series.  If you nevertheless want to upgrade guest additions within
196     NeuroDebian VM, please rebuild the version available from the
197     backports::
198
199       sudo apt-get install -y linux-headers-2.6-amd64 # or -686 for 32bit
200       sudo apt-get install -y -t squeeze-backports virtualbox-ose-guest-dkms \
201            virtualbox-ose-guest-utils  virtualbox-ose-guest-x11
202
203     and reboot VM.
204
205   I am still running an older VirtualBox 3.x
206     Download one of the image files listed below. These older releases
207     are distributed as a `zip` file. Please extract all files from the
208     `.zip` file, using appropriate software for your operating system.
209
210     * `NeuroDebian 6.0.2 image (32bit)
211       <http://neuro.debian.net/debian/vm/neurodebian_6.0.2_i386.zip>`_ [~545MB]
212
213     * `NeuroDebian 6.0.2 image (64bit)
214       <http://neuro.debian.net/debian/vm/neurodebian_6.0.2_amd64.zip>`_ [~560MB]
215
216
217 What has changed
218 ----------------
219
220 .. container:: foldup
221
222   .. container:: expandinstructions
223
224      Click on an item to expand it
225
226   6.999.b4.20130421 -- 22 Apr 2013
227     * Refreshed VM appliance to avoid lengthy initial upgrade
228
229   6.999.b4.20121231 -- 31 Dec 2012
230     * Based on beta 4 release of debian-installer_ for wheezy
231     * Comes with XFCE4_ instead of GNOME_
232
233   6.0.6 -- 01 Oct 2012
234     * Updated core system to Debian squeeze 6.0.6
235
236   6.0.5 -- 10 Nov 2011
237     * Updated core system to Debian squeeze 6.0.3
238     * Updated shipped virtualbox-ose guest-utils and guest-x11 to 4.0.10
239
240       - ``~/host`` is now symlinked to correct path ``/media/sf_host``
241       - ``brain`` user is added to ``vboxsf`` group so mounted host
242         directories should become readily available
243
244     * Root partition size and swap space got doubled in size (40GB
245       and 2GB correspondingly).  Space is allocated dynamically so
246       the actual size of the virtual drive should not grow unless
247       you use it
248
249   6.0.4 -- 13 Jun 2011
250     * Updated shipped virtualbox-ose guest-utils and guest-x11 to 4.0.4
251
252   6.0.3 -- 12 Jun 2011 [Superseded in the archive by 6.0.4]
253     * Updated to Squeeze 6.0.1
254     * Updated VirtualBox guest additions to 4.0.4 from backports.debian.org
255     * Appliance is available as a single file (.ova) ready for the import
256
257   6.0.2 -- 08 Feb 2011
258     * Minor update
259
260   6.0.1 -- 01 Dec 2010
261     * Minor update
262
263 .. include:: link_names.txt