X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=sphinx%2Fvm.rst;h=cc202c4b25b6f8f8bfccc46094e176ebad6b4cec;hb=e6dba5a27889c68cd3f2a98b7b9b81a5b162af69;hp=d3bdd036c074a7e47e0866ea89aff63353a4b3b1;hpb=2be27fb608bb41cc6fda4c4a2ee41bae599080fc;p=neurodebian.git diff --git a/sphinx/vm.rst b/sphinx/vm.rst index d3bdd03..cc202c4 100644 --- a/sphinx/vm.rst +++ b/sphinx/vm.rst @@ -1,134 +1,318 @@ -Standard 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 -Do a minimal install --------------------- -All files in one partition/ -just base system, run selection, but no tasks (not even 'Standard system') +Downloads +--------- +Stable (6.x series) +~~~~~~~~~~~~~~~~~~~ -install new stuff ------------------ +Based on current stable `Debian 6.0 (squeeze)`_ release. This VM +provides a stable, well tested environment with the most of the recent +releases available from NeuroDebian. -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 - +* `NeuroDebian 6.0.6 image (32bit) + `_ [~559MB] -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) + *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.* -# 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 +* `NeuroDebian 6.0.6 image (64bit) + `_ [~576MB] -# 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 + *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.* -# setup etckeeper -etckeeper init +Development (to be 7.x series) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -# 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) +Based on upcoming `Debian 7.0 (wheezy)`_ release. Although already +quite stable, there might be outstanding issues. This VM also +switches from GNOME_ (v.2) desktop environment to XFCE4_. We +recommend this VM over a stable one for anyone needing recent releases +of tools not available for the stable VM (e.g. recent pandas) -- +**getting a complete "Scientific Python" stack with 100s of other +Python modules was never easier**. Moreover your feedback might also +be valuable to polish upcoming Debian wheezy release and NeuroDebian +VM 7.0. -#make sure that xorg.conf has 'vboxvideo' as device driver and also -echo "vboxvideo" >> /etc/modules +* `NeuroDebian 6.999.b4.20121231 image (32bit) + `_ [~656MB] -# 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) +* `NeuroDebian 6.999.b4.20121231 image (64bit) + `_ [~660MB] -# 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 +Historical +~~~~~~~~~~ -# neuro-stuff -aptitude install afni afni-atlases amide caret dicomnifti fsl fsl-atlases lipsia - minc-tools odin psychopy python-mvpa python-pyepl +Virtual appliances above carry guest additions for 4.x series of the +VirtualBox. If you still have VirtualBox 3.x, use previous 6.0.2 +virtual appliances: -# general scientifically useful stuff -aptitude install ipython python-h5py +* `NeuroDebian 6.0.2 image (32bit) + `_ [~545MB] +* `NeuroDebian 6.0.2 image (64bit) + `_ [~560MB] -user config ------------ -# put use home dir in git to be able to track changes -git init +.. note:: -mkdir -p /home/brain/.config/backgrounds -cp /mnt/host/.config/awesome/hotbrain.png /home/brain/.config/backgrounds/ + This older virtual appliances are distributed as a `zip` file. Please + extract all files from the `.zip` file, using appropriate software + for your operating system. -#change menu icon -sudo cp /mnt/host/hacking/neurodebian/artwork/icon.svg /usr/share/icons/Mist/scalable/places/start-here.svg +.. 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. -Deploy ------- +* `VirtualBox download page `_ (Windows, Linux, Mac, + Solaris) -# shrink VDI image by writting to a new (unfragmented) image -# target VDI needs to have proper partition table and MBR + *This webpage offers installers of the VirtualBox application, as well as the + documentation.* -# clone HDD -#dd if=dev/hda of=/dev/hdb bs=512 count=1 -# fixing bits extended partition is empty -> create swap partition -#fdisk /dev/hdb -#mkswap /dev/hdb5 -#mkfs.ext3 -m 1 /dev/hdb1 -#tune2fs -c 100 /dev/hdb1 +Changes +------- +6.999.b4.20121231 -- 31 Dec 2012 -cd /tmp -cp /home/neurodebian/vm/nd_plainpartition.vdi nd_hdd.vdi -mkdir -p vbdev/src vbdev/dest vbmnt/src vbmnt/dest + * Based on beta 4 release of debian-installer_ for wheezy + * Comes with XFCE4_ instead of GNOME_ -# get access to disks inside the VDIs -sudo vdfuse -f /home/neurodebian/vm/nd_master.vdi vbdev/src/ -sudo vdfuse -f nd_hdd.vdi vbdev/dest/ +6.0.6 -- 01 Oct 2012 + * Updated core system to Debian squeeze 6.0.6 +6.0.5 -- 10 Nov 2011 -# mount partititions -sudo mount -o loop vbdev/src/Partition1 vbmnt/src -sudo mount -o loop vbdev/dest/Partition1 vbmnt/dest + * Updated core system to Debian squeeze 6.0.3 + * Updated shipped virtualbox-ose guest-utils and guest-x11 to 4.0.10 -# now extract files from src, filter, and move to dest -sudo rsync -xaHD --delete \ - --exclude=dev \ - --exclude=proc \ - --exclude=tmp \ - --exclude=var/cache/apt \ - --exclude=var/log/* \ - --exclude=etc/.git \ - --exclude=home/brain/.git \ - --exclude=var/lib/apt/lists \ - vbmnt/src/ vbmnt/dest/ + - ``~/host`` is now symlinked to correct path ``/media/sf_host`` + - ``brain`` user is added to ``vboxsf`` group so mounted host + directories should become readily available -sudo umount vbmnt/dest -sudo umount vbmnt/src -sudo umount vbdev/dest -sudo umount vbdev/src + * Root partition size and swap space got doubled in size (40GB + and 2GB correspondingly). Space is allocated dynamically so + the actual size of the virtual drive should not grow unless + you use it +6.0.4 -- 13 Jun 2011 + + * Updated shipped virtualbox-ose guest-utils and guest-x11 to 4.0.4 + +6.0.3 -- 12 Jun 2011 [Superseded in the archive by 6.0.4] + + * Updated to Debian squeeze 6.0.1 + * Updated VirtualBox guest additions to 4.0.4 from backports.debian.org + * Appliance is available as a single file (.ova) ready for the import + +6.0.2 -- 08 Feb 2011 + +6.0.1 -- 01 Dec 2010 + +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. + + + +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. + +.. raw:: html + + + +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 Downloads_ section. Start VirtualBox and select "Import Appliance" from the file +menu. + +.. 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 `.ova` (or extracted +`.ovf` for older appliances shipped as `.zip`) file. + +.. image:: pics/vm_import_wizard.jpg + +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. + +.. 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 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 and mark it to be auto-mounted. Note, the folder name is simply a label. Your directory will +not be renamed. + +.. image:: pics/vm_host_folder.jpg + +If you have a large screen you should increase the display memory to +32 MB in the *Display* settings. Also you might like to enable the +support for 3D Acceleration + +.. image:: pics/vm_settings_display.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. + +.. 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`. In most cases, however, you should not be forced to type +the password, since `sudo` is configured to work without it. + +.. 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. + + +Working with the virtual machine +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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. + +.. 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. + +I have upgraded VirtualBox from 3.x series to 4.x, and my VM lost +mounted host directories. + + NeuroDebian VMs prior 6.0.3 were shipped with guest additions from + 3.x series of VirtualBox and some initial versions of VirtualBox in + 4.x series have failed to mount host directories properly. + VirtualBox 4.0.8 seems to work fine with guest additions from 3.x + series. If you nevertheless want to upgrade guest additions within + NeuroDebian VM, please rebuild the version available from the + backports:: + + sudo apt-get install -y linux-headers-2.6-amd64 # or -686 for 32bit + sudo apt-get install -y -t squeeze-backports virtualbox-ose-guest-dkms \ + virtualbox-ose-guest-utils virtualbox-ose-guest-x11 + + and reboot VM. + +.. include:: link_names.txt