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 Chroot workaround for fslview (HOWTO)
   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 sooner or later
  18 because of that those tools get removed from the repository.
  19
  20 That is what happened with fslview_ tool from FSL_ suite.  Today, at
  21 the end of 2011, it still relies on Qt library version 3 and VTK GUI
  22 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.  So nowadays fslview_ package is
  40 present only in the previous 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 a new release of fslview_ compatible with Qt4
  55 there are possible workarounds to keep research going on
  56 bleeding edge Debian-based 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, could be as
  73 easily upgraded 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 (600 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      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 the 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 be able already 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, or not, to become root for above operations
 147      depending either you are a part of ``staff`` user group.
 148
 149 Optional steps
 150 --------------
 151
 152 Although at this point you can run fslview from the chroot-ed
 153 environment, we would suggest a few additional steps.  For some of
 154 them (marked with **chroot-root**) you would need to become root in a
 155 chroot environment via following steps:
 156
 157 - enter chroot using ``schroot -c squeeze -p``
 158
 159 - become root (via ``su`` command, root password should be the same as
 160   on the main system)
 161
 162 So here are recommended optional additions:
 163
 164 - **chroot-root**: `Enable NeuroDebian repository
 165   <http://neuro.debian.net/#how-to-use-this-repository>`_. Choose
 166   ``squeeze`` release and mirror of preference (remove ``sudo`` from
 167   provided cmdline).
 168
 169 - **chroot-root**: Enable security and functionality updates::
 170
 171    sed -e 's,squeeze,squeeze-updates,g' /etc/apt/sources.list > /etc/apt/sources.list.d/updates.list
 172    echo 'deb http://security.debian.org/ stable/updates main' > /etc/apt/sources.list.d/security.list
 173    apt-get update
 174    apt-get upgrade
 175
 176 - Make fsl atlases accessible within the chroot environment.  There
 177   are two ways and you must choose only **one** of them, otherwise
 178   you might damage your "main" system installation.
 179
 180   - **chroot-root**: Install atlases packages in the chroot-ed environment::
 181
 182      apt-get install fsl-atlases
 183
 184     Although this is the best/correct way it would require additional 200MB of
 185     space, possibly duplicating what you already have installed in the
 186     main system.  Also it requires `enabling of NeuroDebian repository
 187     in chroot environment
 188     <http://neuro.debian.net/#how-to-use-this-repository>`_.
 189
 190   - Alternatively you can bind-mount those directories with atlases installed on the "main"
 191     system within chroot.  For that edit (as root on the "main"
 192     system) ``/etc/schroot/default/fstab`` and add following entries::
 193
 194      /usr/share/fsl/data/atlases /usr/share/fsl/data/atlases none rw,bind 0 0
 195      /usr/share/data             /usr/share/data             none rw,bind 0 0
 196
 197     .. note::
 198        Similarly you can bind-mount any other directory you would like
 199        to make visible in chroot.  Just be careful to not "overlap"
 200        with system directories in chroot which already carry something.
 201
 202 Also you might like to read ``man schroot`` on how to enable
 203 persistent sessions so that chroot initiation could be done ones
 204 during boot instead of per each fslview invocation
 205
 206 If you have any comments (typos, improvements, etc) -- feel welcome to
 207 leave a comment below, or just email `us@NeuroDebian`_ .
 208
 209 .. _us@NeuroDebian: http://neuro.debian.net/#contacts