X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=sphinx%2Fvm.rst;h=1701ddb68eb705741c3bd2f7bb906e06c5b38e9d;hb=HEAD;hp=846b40aa5aa46864d621890be17f45ad69955da8;hpb=f94872cf4b9ac885baf6bb6d61abfbfcbc7d0f37;p=neurodebian.git diff --git a/sphinx/vm.rst b/sphinx/vm.rst index 846b40a..1701ddb 100644 --- a/sphinx/vm.rst +++ b/sphinx/vm.rst @@ -1,81 +1,295 @@ -Standart Debian install +.. _chap_vm: -hostname: neurodebian -domain: '' +NeuroDebian Virtual Machine +=========================== -all file in one partition +`Installation`_ | `Working with the virtual machine`_ | `Troubleshooting`_ | +`What has changed`_ -root: not there -user: brain -pwd: neurodebian +.. quotes:: + :random: 1 + :tags: vm +For all systems running a non-Debian-based operation system, such as MS Windows +or Mac OS X, we offer a `virtual machine`_ that can be equipped with a large +variety of neuroscience software with just a few mouse clicks (e.g. AFNI_, +FSL_, PyMVPA_). -Do a minimal install --------------------- +.. _virtual machine: http://en.wikipedia.org/wiki/Virtual_machine -make separte vdi images for +The virtual machine contains an installation of `Debian 7.0 (wheezy)`_ with a +XFCE4_ desktop environment. All installed software comes from standard Debian +packages, or prospective Debian packages from NeuroDebian. The virtual machine +can be seen as a showcase of what Debian for neuroscience research feels like. +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 +Even on Debian-based systems this virtual machine is an excellent way to +maintain an analysis environment that remains identical throughout the lifetime +of a study and that can be archived alongside acquired data and publications. +This is a much more practical way than freezing the entire software stack of a +whole workstation, where it quickly becomes troublesome to combine the desire +for latest research methodology for new studies and the need for stability for +ongoing projects. -just base system, run selection, but no tasks +Installation +~~~~~~~~~~~~ -install new stuff ------------------ +The following instructions demonstrate how to install the NeuroDebian virtual +machine -- here shown exemplary for Mac OS X, but the procedure is virtually +identical on a Windows box. There is also a video tutorial at coffee break +length. `[Virtual machine setup video tutorial] +`_. -Add sources.list for backports and neurodebian +If you don't have t already, 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. -wget -O - http://backports.org/debian/archive.key | apt-key add - -wget -O - http://neuro.debian.net.asc | apt-key add - +.. _VirtualBox: http://www.virtualbox.org -install kernel 2.6.27 (or later) from backports to have support for OpenGL -direct rendering in VirtualBox +Obtain the most recent version of the NeuroDebian virtual machine by visiting +http://neuro.debian.net and selecting your operating system and a download +server on the frontpage. -# 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 +Start VirtualBox and select "Import Appliance" from the file menu. -# 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_app.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) +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. -#make sure that xorg.conf has 'vboxvideo' as device driver and also -echo "vboxvideo" >> /etc/modules +.. image:: pics/vm_import_wizard.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 +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. -# 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_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. -# 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_host_folder.jpg -# general scientifically useful stuff -aptitude install ipython +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 -mkdir -p .config/backgrounds -cp /mnt/host/.config/awesome/hotbrain.png .config/backgrounds/ +.. image:: pics/vm_settings_display.jpg -#change menu icon -sudo cp /mnt/host/hacking/neurodebian/artwork/icon.svg /usr/share/icons/Mist/scalable/places/start-here.svg +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. This is the default account: + +:user: brain +:password: neurodebian + +:root password: neurodebian + +In most cases you should not be forced to type the password, because ``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 NeuroDebian virtual machine has very low maintenance demands. We have +prepared a short video demo that shows most typical procedures that you will +probably perform while working with NeuroDebian inside a virtual machine: +use the virtual machine in full-screen and seamless mode, shared folder access, +software installation, as well as suspending and resuming the +virtual machine. `[Virtual machine handling video tutorial] +`_ + + +.. _chap_vm_troubleshooting: + +Troubleshooting +~~~~~~~~~~~~~~~ + +.. container:: foldup + + .. container:: expandinstructions + + Click on an item to expand it + + 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``. + + Our proxy setup at work prevents APT from downloading packages + APT needs to be told how to access the proxy. Talk to your local sysadmin + and ask for the proxy's address (maybe a username and password too), as well + as the ports for HTTP and FTP proxies. With this information add the + following lines in the file, /etc/apt/apt.conf.d/80proxy. This will ensure + that after an upgrade changes won't be lost:: + + Acquire::http::proxy "http://:@:/"; + Acquire::ftp::proxy "ftp://:@:/"; + Acquire::https::proxy "https://:@:/"; + + 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. + + My VM lost mounted host directories after upgrading from VirtualBox from 3.x to 4.x + 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-`dpkg --print-architecture` + sudo apt-get install -y -t squeeze-backports virtualbox-ose-guest-dkms \ + virtualbox-ose-guest-utils virtualbox-ose-guest-x11 + + and reboot VM. + + My VM lost mounted host directories, and display auto-resizing after upgrade + NeuroDebian VMs ship without Linux kernel headers pre-installed to + minimize distribution/running footprint for one time throw-away + usages of the VM. To install headers package(s) just run + + sudo apt-get install -y linux-headers-`dpkg --print-architecture` + + and reboot VM. + + I am still running an older VirtualBox 3.x + Download one of the image files listed below. These older releases + are distributed as a `zip` file. Please extract all files from the + `.zip` file, using appropriate software for your operating system. + + * `NeuroDebian 6.0.2 image (32bit) + `_ [~545MB] + + * `NeuroDebian 6.0.2 image (64bit) + `_ [~560MB] + + +What has changed +---------------- + +.. container:: foldup + + .. container:: expandinstructions + + Click on an item to expand it + + 7.8.0 -- 2 Feb 2015 + * VM appliance based on the updated wheezy point release 7.8.0. + Should resolve problems with upgrades of the guest additions. + + 7.4.20140423 -- 24 Apr 2014 + * VM appliance based on the updated wheezy point release 7.4. + Should resolve problems with upgrades of the guest additions. + See http://neuro.debian.net/faq.html#comment-1351846812 + + 7.4.0 -- 28 Feb 2014 + * VM appliance based on the official wheezy point release 7.4. + + 7.2.0 -- 03 Nov 2013 + * VM appliance based on the official wheezy point release 7.2. + * Ships with updated neurodebian-* packages: + - installs ipython notebook and qtconsole for "Scientific Python" + and "PyMVPA tutorial" welcome wizard choices. + + 7.0.0 -- 15 May 2013 + * VM appliance based on the official wheezy release. + * Uses xfce4-terminal by default (instead of urxvt/rxvt-unicode as + in beta-releases) + + 6.999.b4.20130421 -- 22 Apr 2013 + * Refreshed VM appliance to avoid lengthy initial upgrade + + 6.999.b4.20121231 -- 31 Dec 2012 + * Based on beta 4 release of debian-installer_ for wheezy + * Comes with XFCE4_ instead of GNOME_ + + 6.0.6 -- 01 Oct 2012 + * Updated core system to Debian squeeze 6.0.6 + + 6.0.5 -- 10 Nov 2011 + * Updated core system to Debian squeeze 6.0.3 + * Updated shipped virtualbox-ose guest-utils and guest-x11 to 4.0.10 + + - ``~/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 + + * 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 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 + * Minor update + + 6.0.1 -- 01 Dec 2010 + * Minor update + +.. include:: link_names.txt