1 :date: 2011-12-09 16:08:00
2 :tags: debian, neuroscience, software, FSL, fslview, chroot, virtualization
4 .. _chap_schroot_fslview:
6 Chroot workaround for fslview (HOWTO)
7 =====================================
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.
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
21 .. _Qt3: http://doc.qt.nokia.com/3.3/
25 Last version of Qt3, 3.3.8, was released in February 2007, with
26 official support by Trolltech terminated later that year.
28 Qt4 was first released in 2005, and current stable series 4.7
29 released appeared in September 2010.
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.
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
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
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.
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.
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
89 For this exercise you would need
91 - 3--20 minutes depending on the bandwidth to the Debian mirror and
92 efficiency in cut/paste operations
94 - root access to the system while performing this setup, although
95 end-users of fslview would not need root access after everything
98 - 2 additional tools -- debootstrap_ to install Debian in a directory
99 and a convenience utility schroot_ to "enable" such an environment
101 .. _debootstrap: http://wiki.debian.org/Debootstrap
102 .. _schroot: http://packages.debian.org/sid/schroot
108 - Install the tools::
110 sudo apt-get install debootstrap schroot
112 - Choose a location with enough space (600 MB should be enough) and
113 install a complete Debian squeeze installation with fslview::
115 sudo debootstrap --include=fslview squeeze /srv/chroots/squeeze http://ftp.us.debian.org/debian
118 You might like to adjust the URL to a `Debian mirror`_ closer to you
120 .. _`Debian mirror`: http://www.debian.org/mirror/list
122 - Create schroot_ configuration file ``/etc/schroot/chroot.d/squeeze``
123 with the following content::
126 description=Debian squeeze (6.x stable)
128 directory=/srv/chroots/squeeze
130 aliases=debian,default
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.)
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::
140 echo -e '#!/bin/sh\nschroot -p -c squeeze /usr/bin/fslview "$@"' > /usr/local/bin/fslview
141 chmod a+x /usr/local/bin/fslview
144 You might need to become root for the above.
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:
154 - enter chroot using ``schroot -c squeeze -p``
156 - become root (via ``su`` command, root password should be the same as
159 So here are recommended optional additions:
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
166 - **chroot-root**: Enable security and functionality updates::
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
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.
177 - **chroot-root**: Install atlases packages in the chroot-ed environment::
179 apt-get install fsl-atlases
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>`_.
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::
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
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.
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.
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
209 If you have any comments (typos, improvements, etc) -- feel welcome to
210 leave a comment below, or just email `us@NeuroDebian`_ .
212 .. _us@NeuroDebian: http://neuro.debian.net/#contacts