X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=sphinx%2Fvm.rst;h=126eba2d9389b74340d291ea425143e3182f9ae9;hb=1004aab2b94f99ef4c66bafd9ee52a1a8aeceb3c;hp=ffe579c71075d409ccb09f36e90687ee95bd2d5b;hpb=f9d9b4bbebf84e86516733195b8ab1420f1d9435;p=neurodebian.git diff --git a/sphinx/vm.rst b/sphinx/vm.rst index ffe579c..126eba2 100644 --- a/sphinx/vm.rst +++ b/sphinx/vm.rst @@ -1,94 +1,217 @@ -Standart Debian install +.. _chap_vm: -hostname: neurodebian -domain: '' +NeuroDebian Virtual Machine +=========================== -all file in one partition +.. quotes:: + :random: 1 + :tags: vm -root: not there -user: brain -pwd: neurodebian +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 +.. _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 -Do a minimal install --------------------- -make separte vdi images for +Downloads +--------- + +* `NeuroDebian 6.0.2 image (32bit) + `_ [~545MB] + + *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.2 image (64bit) + `_ [~560MB] + + *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.* + +.. note:: + + You can verify that you have downloaded archives correctly using + `md5sums -c MD5SUMS + `_ . You can also verify + the authenticity of the `MD5SUMS + `_ itself using `gpg + --verify MD5SUMS.gpg + `_ signed with + NeuroDebian archive key. + +* `VirtualBox download page `_ (Windows, Linux, Mac, + Solaris) + + *This webpage offers installers of the VirtualBox application, as well as the + documentation.* + + +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. 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. -* / -* /tmp -* /var/cache/apt -* swap +.. _Debian 6.0 (squeeze): http://www.debian.org/releases/squeeze +.. _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. -just base system, run selection, but no tasks +.. raw:: html + -install new stuff ------------------ +First download and install a recent version of VirtualBox_. VirtualBox is a +virtualization software that is freely available for Windows, MacOS X, Solaris, +and Linux. VirtualBox comes with a comprehensive manual that should answer +potential questions regarding installation and maintenance. -Add sources.list for backports and neurodebian +.. _VirtualBox: http://www.virtualbox.org -wget -O - http://backports.org/debian/archive.key | apt-key add - -wget -O - http://neuro.debian.net.asc | apt-key add - +Next, download the most recent version of the NeuroDebian virtual machine from +the Downloads_ section. The machine is distributed as a zip file. Please +extract this file, using appropriate software for your operating system. +Once extracted, start VirtualBox and select "Import Appliance" from the file +menu. -install kernel 2.6.27 (or later) from backports to have support for OpenGL -direct rendering in VirtualBox +.. image:: pics/vm_import_app.jpg -# a basic desktop -aptitude install \ - alacarte desktop-base evince file-roller gcalctool gdm gksu gnome-core - gnome-keyring gnome-utils gnome-volume-manager gnome-mount gthumb - bash-completion less mc gnome-themes +The next dialog will ask you to choose a virtual machine. Please navigate to the +extracted NeuroDebian download and select the `.ovf` file. -# cleanup unwanted stuff -# video drivers (all but vesa) -aptitude purge $(apt-cache search --names-only --installed xserver-xorg-video | grep xserver-xorg-video | cut -d ' ' -f 1,1) xserver-xorg-video-vesa+ -# random stuff -aptitude purge radeontool sound-juicer +.. image:: pics/vm_import_wizard.jpg -# prepare for kernel module building (guest additions) -aptitude install module-assistant -module-assistant prepare -bash /media/cdrom/VBoxLinuxAdditions-amd64.run (need 2.6.27+ kernel for direct rendering) +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. If +you have a large screen you should increase the display memory to 32 MB in the +*Display* settings. -#make sure that xorg.conf has 'vboxvideo' as device driver and also -echo "vboxvideo" >> /etc/modules +.. image:: pics/vm_add_host_folder.jpg -# make user brain allowed to execute sudo without a password -adduser brain sudo -visudo -# and uncomment the respective line at the end of the file -# (make sure there is nothing below it +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. -# configure shared folders -mkdir /mnt/host -mount -t vboxsf host /mnt/host -# better put the following into the session startup config of the user -sudo mount -t vboxsf -o defaults,uid=brain,gid=brain host /mnt/host +.. image:: pics/vm_host_folder.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, 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. -# neuro-stuff -aptitude install afni afni-atlases amide caret dicomnifti fsl fsl-atlases lipsia - minc-tools odin psychopy python-mvpa python-pyepl +.. image:: pics/vm_settings.jpg -# general scientifically useful stuff -aptitude install ipython +The virtual machine logs yourself in automatically. The name of the virtual +machine user is `brain` and the password is `neurodebian`. The *root* password +is also `neurodebian`. In most cases, however, you should not be forced to type +the password, since `sudo` is configured to work without it. -mkdir -p .config/backgrounds -cp /mnt/host/.config/awesome/hotbrain.png .config/backgrounds/ +.. 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. -#change menu icon -sudo cp /mnt/host/hacking/neurodebian/artwork/icon.svg /usr/share/icons/Mist/scalable/places/start-here.svg +Working with the virtual machine +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Deploy ------- +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. -# shrink VDI image by writting to a new (unfragmented) image -# target VDI needs to have proper partition table and MBR -# XXX maybe 'dd' could be used on the fuse-mounted VDIs -sudo ~/vdfuse-v60 -f ~/.VirtualBox/HardDisks/NeuroDebian.vdi mnt/src -sudo ~/vdfuse-v60 -f ~/.VirtualBox/HardDisks/nd_test.vdi mnt/dest -sudo mount -o loop mnt/src/Partition1 src -sudo mount -o loop mnt/dest/Partition1 dest -rsync -vxaHD --delete --exclude=src/dev --exclude=src/proc --exclude=src/tmp src dest +.. raw:: html + + + + +.. _chap_vm_troubleshooting: + +Troubleshooting +~~~~~~~~~~~~~~~ + +Updating the VM or installing new packages doesn't work. + + 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 + + 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. + + 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.