From: Michael Hanke Date: Thu, 21 Jan 2010 01:49:38 +0000 (-0500) Subject: User docs for the VM. X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=c393ab43f636199d95ef3d32567e0c77bbb580d1;p=neurodebian.git User docs for the VM. --- diff --git a/sphinx/pics/vm_add_host_folder.jpg b/sphinx/pics/vm_add_host_folder.jpg new file mode 100644 index 0000000..d7183be Binary files /dev/null and b/sphinx/pics/vm_add_host_folder.jpg differ diff --git a/sphinx/pics/vm_host_folder.jpg b/sphinx/pics/vm_host_folder.jpg new file mode 100644 index 0000000..773b321 Binary files /dev/null and b/sphinx/pics/vm_host_folder.jpg differ diff --git a/sphinx/pics/vm_import_app.jpg b/sphinx/pics/vm_import_app.jpg new file mode 100644 index 0000000..d13d7d3 Binary files /dev/null and b/sphinx/pics/vm_import_app.jpg differ diff --git a/sphinx/pics/vm_import_wizard.jpg b/sphinx/pics/vm_import_wizard.jpg new file mode 100644 index 0000000..1491c41 Binary files /dev/null and b/sphinx/pics/vm_import_wizard.jpg differ diff --git a/sphinx/pics/vm_import_wizard.png b/sphinx/pics/vm_import_wizard.png new file mode 100644 index 0000000..12350fb Binary files /dev/null and b/sphinx/pics/vm_import_wizard.png differ diff --git a/sphinx/pics/vm_settings.jpg b/sphinx/pics/vm_settings.jpg new file mode 100644 index 0000000..b2133a8 Binary files /dev/null and b/sphinx/pics/vm_settings.jpg differ diff --git a/sphinx/vm-notes.txt b/sphinx/vm-notes.txt new file mode 100644 index 0000000..5797217 --- /dev/null +++ b/sphinx/vm-notes.txt @@ -0,0 +1,141 @@ +Standard Debian install + +hostname: neurodebian +domain: '' + +all file in one partition + +root: not there +user: brain +pwd: neurodebian + + +Do a minimal install +-------------------- + +All files in one partition/ +just base system, run selection, but no tasks (not even 'Standard system') + + +install new stuff +----------------- + +Add sources.list for backports and neurodebian +wget -O /etc/apt/sources.list.d/neuro.debian.net.list http://neuro.debian.net/_static/neurodebian.lenny.us.sources.list +echo "deb http://www.backports.org/debian lenny-backports main contrib non-free" >> /etc/apt/sources.list.d/backports.org.list +wget -O - http://backports.org/debian/archive.key | apt-key add - +wget -O - http://neuro.debian.net/_static/neuro.debian.net.asc | apt-key add - + +install kernel 2.6.27 (or later) from backports to have support for OpenGL +direct rendering in VirtualBox +(and deinstall the old one, after a successfull reboot) + +# 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 etckeeper git-core gitk ntpdate + alsa-utils + +# install network manager applet +# but we don't want to have all the openvpn stuff that pull in an armada of +# things: I did it by hand in aptitude + +# 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 + +# setup etckeeper +etckeeper init + +# prepare for kernel module building (guest additions) +aptitude install module-assistant +module-assistant prepare +# note guest additions for 3.1.2 are broken, use 3.1.0 +bash /media/cdrom/VBoxLinuxAdditions-amd64.run (need 2.6.27+ kernel for direct rendering) +#make sure that xorg.conf has 'vboxvideo' as device driver and also +echo "vboxvideo" >> /etc/modules + +# 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) + +# configure shared folders +mkdir /mnt/host +mount -t vboxsf host /mnt/host +# better put the following into the session startup config of the user +# stupid wrapping into bash line to workaround a silly bug in Virtualbox additions +bash -c "cd /; sudo mount -t vboxsf -o defaults,uid=brain,gid=brain host /mnt/host" + + +# neuro-stuff +aptitude install afni afni-atlases amide caret dicomnifti fsl fsl-atlases lipsia + minc-tools odin psychopy python-mvpa python-pyepl python-mvpa-doc + +# general scientifically useful stuff +aptitude install ipython python-h5py vim-python + +# next step purge network interface config to give the power to network manager +# important +adduser brain netdev + + +user config +----------- +# put use home dir in git to be able to track changes +git init + +mkdir -p /home/brain/.config/backgrounds +cp /mnt/host/.config/awesome/hotbrain.png /home/brain/.config/backgrounds/ + +#change menu icon +sudo cp /mnt/host/hacking/neurodebian/artwork/icon.svg /usr/share/icons/Mist/scalable/places/start-here.svg + + +Deploy +------ + +# shrink VDI image by writting to a new (unfragmented) image +# target VDI needs to have proper partition table and MBR +# simplest solution: clonezilla + +# clean up the master COPY +cp ~/vm/nd_master.vdi /tmp/nd_master.vdi +cd /tmp +mkdir -p vbdev vbmnt +# get access to disks inside the VDIs +sudo vdfuse -f nd_master.vdi vbdev +# mount partitition +sudo mount -o loop vbdev/Partition1 vbmnt + +# remove cruft +# package cache +sudo find vbmnt/var/cache/apt/archives/ -name '*.deb' -delete +sudo rm vbmnt/var/cache/apt/*.bin +# device files -- udev restores them +sudo rm -rf vbmnt/dev/* +# tmp +sudo rm -rf vbmnt/tmp/* +# log files +sudo find vbmnt/var/log -type f -delete +# apt lists +sudo find vbmnt/var/lib/apt -type f -name '*debian*' -o -type f -name '*list*' -delete +# history +sudo rm vbmnt/root/.bash_history +sudo rm vbmnt/home/brain/.bash_history + +# unmount filesystem +sudo umount vbmnt +# zero out empty space +sudo zerofree -v vbdev/Partition1 +# close whole VDI +sudo umount vbdev + +# compact VDI +# THIS NEEDS TO BE DONE ON A VDI THAT IS REGISTERED WITH VIRTUALBOX +VBoxManage modifyhd nd_master.vdi --compact + diff --git a/sphinx/vm.rst b/sphinx/vm.rst index 5797217..53a1b44 100644 --- a/sphinx/vm.rst +++ b/sphinx/vm.rst @@ -1,141 +1,110 @@ -Standard Debian install - -hostname: neurodebian -domain: '' - -all file in one partition - -root: not there -user: brain -pwd: neurodebian - - -Do a minimal install --------------------- - -All files in one partition/ -just base system, run selection, but no tasks (not even 'Standard system') - - -install new stuff ------------------ - -Add sources.list for backports and neurodebian -wget -O /etc/apt/sources.list.d/neuro.debian.net.list http://neuro.debian.net/_static/neurodebian.lenny.us.sources.list -echo "deb http://www.backports.org/debian lenny-backports main contrib non-free" >> /etc/apt/sources.list.d/backports.org.list -wget -O - http://backports.org/debian/archive.key | apt-key add - -wget -O - http://neuro.debian.net/_static/neuro.debian.net.asc | apt-key add - - -install kernel 2.6.27 (or later) from backports to have support for OpenGL -direct rendering in VirtualBox -(and deinstall the old one, after a successfull reboot) - -# 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 etckeeper git-core gitk ntpdate - alsa-utils - -# install network manager applet -# but we don't want to have all the openvpn stuff that pull in an armada of -# things: I did it by hand in aptitude - -# 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 - -# setup etckeeper -etckeeper init - -# prepare for kernel module building (guest additions) -aptitude install module-assistant -module-assistant prepare -# note guest additions for 3.1.2 are broken, use 3.1.0 -bash /media/cdrom/VBoxLinuxAdditions-amd64.run (need 2.6.27+ kernel for direct rendering) -#make sure that xorg.conf has 'vboxvideo' as device driver and also -echo "vboxvideo" >> /etc/modules - -# 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) - -# configure shared folders -mkdir /mnt/host -mount -t vboxsf host /mnt/host -# better put the following into the session startup config of the user -# stupid wrapping into bash line to workaround a silly bug in Virtualbox additions -bash -c "cd /; sudo mount -t vboxsf -o defaults,uid=brain,gid=brain host /mnt/host" - - -# neuro-stuff -aptitude install afni afni-atlases amide caret dicomnifti fsl fsl-atlases lipsia - minc-tools odin psychopy python-mvpa python-pyepl python-mvpa-doc - -# general scientifically useful stuff -aptitude install ipython python-h5py vim-python - -# next step purge network interface config to give the power to network manager -# important -adduser brain netdev - - -user config ------------ -# put use home dir in git to be able to track changes -git init - -mkdir -p /home/brain/.config/backgrounds -cp /mnt/host/.config/awesome/hotbrain.png /home/brain/.config/backgrounds/ - -#change menu icon -sudo cp /mnt/host/hacking/neurodebian/artwork/icon.svg /usr/share/icons/Mist/scalable/places/start-here.svg - - -Deploy ------- - -# shrink VDI image by writting to a new (unfragmented) image -# target VDI needs to have proper partition table and MBR -# simplest solution: clonezilla - -# clean up the master COPY -cp ~/vm/nd_master.vdi /tmp/nd_master.vdi -cd /tmp -mkdir -p vbdev vbmnt -# get access to disks inside the VDIs -sudo vdfuse -f nd_master.vdi vbdev -# mount partitition -sudo mount -o loop vbdev/Partition1 vbmnt - -# remove cruft -# package cache -sudo find vbmnt/var/cache/apt/archives/ -name '*.deb' -delete -sudo rm vbmnt/var/cache/apt/*.bin -# device files -- udev restores them -sudo rm -rf vbmnt/dev/* -# tmp -sudo rm -rf vbmnt/tmp/* -# log files -sudo find vbmnt/var/log -type f -delete -# apt lists -sudo find vbmnt/var/lib/apt -type f -name '*debian*' -o -type f -name '*list*' -delete -# history -sudo rm vbmnt/root/.bash_history -sudo rm vbmnt/home/brain/.bash_history - -# unmount filesystem -sudo umount vbmnt -# zero out empty space -sudo zerofree -v vbdev/Partition1 -# close whole VDI -sudo umount vbdev - -# compact VDI -# THIS NEEDS TO BE DONE ON A VDI THAT IS REGISTERED WITH VIRTUALBOX -VBoxManage modifyhd nd_master.vdi --compact - +NeuroDebian Virtual Machine +=========================== + +Those, who are not yet running a Debian-based operating system, but are already +tired of fiddling with dozens of neuro-software packages, can get a glimpse of +neuroscience research in a Debian environment via a `virtual machine`_. + +.. _virtual machine: http://en.wikipedia.org/wiki/Virtual_machine + +NeuroDebian offers a virtual machine that comes preinstalled with a number +of popular neuroscience packages (e.g. AFNI_, Caret_, FSL_, PyMVPA_). + +.. _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 + +The virtual machine contains an installation of `Debian 5.0 (lenny)`_ with a +GNOME_ desktop environment. All installed software comes from standard Debian +packages, or prospective Debian packages from NeuroDebian -- no custom +installations whatsoever. This means that all contained software is readily +available for any system running a Debian operating system (or recent Ubuntu +releases). 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 +bugfixed for the whole operating system provided by the Debian project, as well +as software updates for neuroscience-related packages. + +.. _Debian 5.0 (lenny): http://www.debian.org/releases/stable +.. _GNOME: http://www.gnome.org/ + + +Installation +------------ + +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. + +.. _VirtualBox: http://www.virtualbox.org + +Next, download the most recent version of the NeuroDebian virtual machine from +the `download page`_ (about 1GB download size). The machine is distributed as a +`tar` file. Please extract this file, using appropriate software for your +operating system. Every Linux system comes with the `tar` commandline utility, +and potentially other graphical archivers that can extract this format. MacOS X +users can simply double-click such file to extract it. Windows users can extract +it with, for example, 7zip_. + +Once extracted, you'll find a directory with three files. Now start VirtualBox, +and select "Import Appliance" from the file menu. + +.. _download page: http://neuro.debian.net/debian/vm +.. _7zip: http://www.7-zip.org/ + +.. image:: pics/vm_import_app.jpg + +The next dialog will ask you to choose a virtual machine. Please navigate to the +extracted NeuroDebian download and select the `NeuroDebian.ovf` file. + +.. image:: pics/vm_import_wizard.jpg + +You can finished the import wizard by click on *next* a couple of times. There +is no need to change anything, as we will got through the settings in a second. +Importing the virtual machine will take a short while, as it is distributed in +a compressed format that now gets extracted (total extracted size about 3.5 +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 the 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. + +.. image:: pics/vm_add_host_folder.jpg + +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 a computer with the need to duplicate it or use the +network. The virtual machine is preconfigured to access a shared folder named +labeled "host". Simple click on the *add* button 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. + +.. 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 that shows the boot process. After a short while the NeuroDebian desktop +will appear. You can now explore the system. The virtual machine is connect +with your host computer, and shares its internet connection. Via this +connection you can update the contained software packages at any time. + +.. warning:: + + VirtualBox might offer you to upgrade the "guest additions" to version 3.1.2. + Do **not** do this, since this version is broken, and after the upgrade you + will now longer be able to use the mouse inside the virtual machine. + +.. image:: pics/vm_settings.jpg + +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`. + +Enjoy!