sandbox/schroot-fslview.rst

   1 :date: 2011-12-09 16:08:00
   2 :tags: debian, neuroscience, software, FSL, fslview, chroot, virtualization
   3
   4 .. _chap_schroot_fslview:
   5
   6 "Install" fslview on recent systems
   7 ===================================
   8
   9 Preamble
  10 --------
  11
  12 Sometimes research software projects start to lag behind recent
  13 developments in the libraries they rely upon because necessary changes
  14 to the code might require
  15 considerable effort, and thus time.  That leads to
  16 inability to build those tools using up-to-date versions of libraries
  17 available on the system due to incompatible API, and those
  18 tools get removed from the repository.
  19
  20 That is the situation which happened with fslview_ tool from FSL_
  21 suite.  At the moment it still relies on Qt library version 3 and VTK
  22 GUI support for it.
  23
  24 .. note::
  25
  26    Last version of Qt3, 3.3.8, was released in February 2007, with
  27    official support by Trolltech terminated later that year.
  28
  29    Qt4 was first released in 2005, and current stable series 4.7
  30    released appeared in September 2010.
  31
  32 Because of the age and discontinued upstream support, `Qt3 was
  33 orphaned`_ in Debian, and tools relying on it were encouraged to
  34 migrate to use Qt4.  As a result, although Qt3 itself is still present
  35 in Debian (and thus Ubuntu), VTK GUI support for Qt3 (package
  36 `libvtk5.4-qt3`_) which fslview uses, was removed from Debian due to
  37 Qt3 deprecation.  Once again, it was not removed just to annoy people,
  38 but rather because it became unfeasible to maintain its robust building
  39 and functioning.  As the result, fslview_ package is currently
  40 present only in the releases of Debian and Ubuntu which carry
  41 libvtk5.4-qt3 library.  Those are -- Debian squeeze (stable), Ubuntu
  42 nutty and maverick.  If you upgraded your system from one of those
  43 releases, good chance is that you still have fslview (and required
  44 libraries) installed although not available from the APT repository
  45 you are using.  They
  46 might even work.  But fresh systems installations will not have them.
  47
  48 .. _`Qt3 was orphaned`: http://lists.debian.org/debian-devel/2011/05/msg00236.html
  49 .. _`libvtk5.4-qt3`: http://packages.debian.org/search?keywords=libvtk5.4-qt3
  50
  51 Workaround
  52 ----------
  53
  54 While everyone is waiting for fslview_ to become compatible with Qt4
  55 there are possible workarounds meanwhile to keep research going on
  56 bleeding edge releases.  The first, obvious choice for a FOSS
  57 enthusiast, is to build fslview_ from source by first building VTK Qt3
  58 bindings.  While it might be educationally valuable and exciting, we
  59 are afraid in the end it might be more frustrating than useful.
  60
  61 Therefore we would like to suggest another, much more straightforward
  62 and hopefully painless approach -- lightweight virtualization, or chroot_
  63 jailing, which exists in Unix-land since 1970s.
  64 With this exercise in **4 simple steps** we will install a
  65 complete (minimalistic) installation of Debian stable into a separate
  66 directory.  We will provide a convenience wrapper to
  67 run fslview as if it was installed on the "main" system.  So your
  68 system will stay intact while you would enrich it with additional
  69 installation of stable Debian. Moreover if
  70 security or critical fixes to any components of that installation
  71 become available, this chroot
  72 environment, being a complete Debian installation, would be as
  73 easily upgradeable as your main system, thus guaranteeing robust performance.
  74
  75 Although we demonstrate this setup with fslview in mind, such approach
  76 is generally useful for various use cases.  E.g. we have used it in
  77 the opposite situation -- on stable Debian systems we needed to run
  78 some software available only from Debian unstable or testing, and
  79 backporting of all required dependencies was either cumbersome or just
  80 impossible without sacrificing stability of the system.
  81
  82 .. _chroot: http://en.wikipedia.org/wiki/Chroot
  83 .. _fslview: http://www.fmrib.ox.ac.uk/fsl/fslview
  84 .. _FSL: http://www.fmrib.ox.ac.uk/fsl
  85
  86
  87 Prerequisites
  88 -------------
  89
  90 For this exercise you would need
  91
  92 - 3--20 minutes depending on the bandwidth to the Debian mirror and
  93   efficiency in cut/paste operations
  94
  95 - root access to the system while performing this setup, although
  96   end-users of fslview would not need root access after everything
  97   is setup
  98
  99 - 2 additional tools -- debootstrap_ to install Debian in a directory
 100   and a convenience utility schroot_ to "enable" such an environment
 101
 102 .. _debootstrap: http://wiki.debian.org/Debootstrap
 103 .. _schroot: http://packages.debian.org/sid/schroot
 104
 105
 106 Procedure
 107 ---------
 108
 109 - Install the tools::
 110
 111    sudo apt-get install debootstrap schroot
 112
 113 - Choose a location with enough space (400 MB should be enough) and
 114   install a complete Debian squeeze installation with fslview::
 115
 116    sudo debootstrap --include=fslview squeeze /srv/chroots/squeeze http://ftp.us.debian.org/debian
 117
 118   .. note::
 119      You might like to adjust URL to the archive to use some closer
 120      closer to you `Debian mirror`_
 121
 122 .. _`Debian mirror`: http://www.debian.org/mirror/list
 123
 124 - Create schroot_ configuration file ``/etc/schroot/chroot.d/squeeze``
 125   with following content::
 126
 127    [squeeze]
 128    description=Debian squeeze (6.x stable)
 129    type=directory
 130    directory=/srv/chroots/squeeze
 131    users=YOURLOGIN
 132    aliases=debian,default
 133
 134   Replace YOURLOGIN with a comma separated list of users who should be
 135   allowed to access this chroot environment (see ``man schroot.conf``
 136   for more options, e.g. how to specify the groups etc.)
 137
 138 - At this point you should already be able to invoke any command
 139   within the chroot environment, so just create a little shell script
 140   ``/usr/local/bin/fslview``, make it executable and be all set::
 141
 142    echo -e '#!/bin/sh\nschroot -p -c squeeze /usr/bin/fslview "$@"' > /usr/local/bin/fslview
 143    chmod a+x /usr/local/bin/fslview
 144
 145   .. note::
 146      You might need to become root for above operations, or not
 147      depending either you are a part of ``staff`` user group.
 148
 149 Optional steps
 150 --------------
 151
 152 Although at this point you are all set to run fslview from the
 153 chroot-ed environment, we would suggest a few additional steps you
 154 would need to perform within the chroot-ed environment. For some of
 155 them (marked with **chroot-root**) you would need to become root in a
 156 chroot using:
 157
 158 - enter chroot using ``schroot -c squeeze -p``
 159
 160 - become root (via ``su`` command, root password should be the same as
 161   on the main system)
 162
 163 So here they are
 164
 165 - **chroot-root**: `Enable NeuroDebian repository
 166   <http://neuro.debian.net/#how-to-use-this-repository>`_. Choose
 167   ``squeeze`` release and mirror of preference (remove ``sudo`` from
 168   provided cmdline).
 169
 170 - **chroot-root**: Enable security and functionality updates::
 171
 172    sed -e 's,squeeze,squeeze-updates,g' /etc/apt/sources.list > /etc/apt/sources.list.d/updates.list
 173    echo 'deb http://security.debian.org/ stable/updates main' > /etc/apt/sources.list.d/security.list
 174    apt-get update
 175    apt-get upgrade
 176
 177 - Make fsl atlases accessible within the chroot environment.  There
 178   are two ways and you need to choose only **one** of them, otherwise
 179   you might damage your "main" system installation.
 180
 181   - **chroot-root**: Install them in a chroot-ed environment::
 182
 183      apt-get install fsl-atlases
 184
 185     Although the best/correct way it would require additional 200MB of
 186     space, possibly duplicating what you already have installed in the
 187     main system.  Also it requires `enabling of NeuroDebian repository
 188     in chroot environment
 189     <http://neuro.debian.net/#how-to-use-this-repository>`_.
 190
 191   - Bind-mount those directories with atlases installed on the "main"
 192     system within chroot.  For that edit (as root on the "main"
 193     system) ``/etc/schroot/default/fstab`` and add following entries::
 194
 195      /usr/share/fsl/data/atlases /usr/share/fsl/data/atlases none rw,bind 0 0
 196      /usr/share/data /usr/share/data none    rw,bind 0 0
 197
 198     .. note::
 199        Similarly you can bind-mount any other directory you would like
 200        to make visible in chroot.  Just be careful to not "overlap"
 201        with system directories in chroot which already carry something.
 202
 203 Also you might like to read ``man schroot`` on how to enable
 204 persistent sessions so that chroot initiation could be done ones
 205 during boot instead of per each fslview invocation
 206
 207 If you have any comments (typos, improvements, etc) -- feel welcome to
 208 leave a comment below, or just email `us@NeuroDebian`_ .
 209
 210 .. _us@NeuroDebian: http://neuro.debian.net/#contacts