sphinx/blog/2011/2011-12-12_schroot_fslview.rst

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