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