1 Introduction
2 ------------
3
4 The userinstall distribution consists of a number of scripts, together with a
5 short configuration file, which allows non-root users to set up and use their
6 own package and dependency management facilities and to download and install
7 Debian packages without having to obtain root privileges. The software within
8 installed packages may then be used, subject to certain constraints such as
9 program environments, library paths, and so on. In effect, userinstall
10 provides a personal package manager.
11
12 Contact, Copyright and Licence Information
13 ------------------------------------------
14
15 The current Web page for userinstall at the time of release is:
16
17 http://www.boddie.org.uk/paul/userinstall.html
18
19 Copyright and licence information can be found in the docs directory - see
20 docs/COPYING.txt and docs/gpl-3.0.txt for more information.
21
22 Thanks to Piotr Roszatycki, the maintainer of fakechroot, for helpfully fixing
23 system call coverage in that utility in order to support cross-distribution
24 bootstrapping.
25
26 Dependencies
27 ------------
28
29 fakeroot Tested with 1.5.10ubuntu2
30 fakechroot 2.8 or later required
31 debootstrap Tested with 0.3.3.2ubuntu3 on Ubuntu Hoary 5.04, 1.0.7~feisty1
32 on Ubuntu Feisty 7.04, 1.0.20~hardy1 on Ubuntu Hardy
33
34 New in userinstall 0.2 (Changes since userinstall 0.1)
35 ------------------------------------------------------
36
37 * Fixed an argument parsing error in the user-setup script.
38 * Adopted lsb-release environment variables instead of new ones like
39 DISTNAME, exposing derivatives of these variables by default.
40 * Added explicit keyring package installation.
41 * Added scripts for configuring and entering the chroot.
42 * Added support for UML instance construction from distribution
43 installations.
44
45 Configuration
46 -------------
47
48 If the system defaults are not to be used, or if userinstall is not installed
49 as a system package, the userinstall-defaults file supplied with the
50 distribution may be edited to specify the nature and location of the personal
51 package manager.
52
53 The following settings can be edited:
54
55 USERINSTALL_ID This should reflect the distribution being used or, in
56 special cases, a different distribution. Examples
57 include Debian and Ubuntu.
58
59 USERINSTALL_CODENAME This should reflect the version of the distribution
60 being used and need only be altered in special
61 situations (such as the creation of a sandbox for
62 testing other distributions).
63
64 Examples of codenames include hardy and jaunty for
65 Ubuntu and lenny and squeeze for Debian. Note that the
66 setup process may not work with different distributions
67 due to library incompatibilities.
68
69 PACKAGEROOT The location of the personal package manager in the
70 filesystem.
71
72 See the /etc/lsb-release file for example values describing your own system,
73 with the DISTRIB prefix used instead of the USERINSTALL prefix for each of the
74 settings.
75
76 If a completely new userinstall-defaults file is created, it is essential that
77 the above variables be defined so that the scripts know where to create or to
78 find the personal package manager.
79
80 Creating a Personal Package Manager
81 -----------------------------------
82
83 In order to install packages as a non-root user, first invoke the user-setup
84 script; this will create and initialise a basic Debian system with a basic set
85 of packages installed. For example, with userinstall installed as a system
86 package, using the system defaults:
87
88 user-setup
89
90 Or with defaults in the current directory:
91
92 ./user-setup
93
94 It is possible to override the "template" for the system by specifying a
95 "mirror" location. This is useful if you have the CD or DVD image for the
96 distribution already mounted in the filesystem. For example:
97
98 user-setup file:///cdrom
99
100 sudo mount -o loop /home/me/downloads/kubuntu-7.04-alternate-i386.iso /tmp/cdrom
101 user-setup file:///tmp/cdrom
102
103 An URI must be specified as the "mirror" location, not a normal filename.
104
105 Once the installation is complete, some post-installation is necessary:
106
107 user-postsetup
108
109 If a different distribution is being used for the package manager than that
110 being run on the system, it might be necessary to specify a country code so
111 that the configuration of package repositories can be performed successfully.
112 For example, for repositories mirrored in the United Kingdom (UK):
113
114 user-postsetup uk
115
116 At this point, the package manager should be ready to use.
117
118 Adding Package Repositories to the Package Manager
119 --------------------------------------------------
120
121 To get access to repositories of packages beyond those provided by the basic
122 distribution, edit the /etc/apt/sources.list file inside the system. The
123 user-path script can help you find the exact location of the file:
124
125 user-path /etc/apt/sources.list
126
127 Or with defaults in the current directory:
128
129 ./user-path /etc/apt/sources.list
130
131 And you can edit the file directly with a text editor (such as vi) as follows:
132
133 vi `user-path /etc/apt/sources.list`
134
135 Or with defaults in the current directory:
136
137 vi `./user-path /etc/apt/sources.list`
138
139 Installing Packages
140 -------------------
141
142 To install packages from other repositories, invoke the user-apt-get script
143 with the options expected by the regular apt-get program. For example:
144
145 user-apt-get --help
146 user-apt-get update
147
148 It may be necessary to install the gnupg package to enable package signature
149 verification:
150
151 user-apt-get install gnupg
152
153 Then, other packages can be installed. For example:
154
155 user-apt-get install python-cmdsyntax
156
157 Provided that the specified packages are known and their dependencies can be
158 met, they will be installed into the system.
159
160 Installing Single Packages
161 --------------------------
162
163 To install individual package files, invoke the user-dpkg-i script with the
164 name of the package file. For example:
165
166 user-dpkg-i /home/me/downloads/python-cmdsyntax_0.91-0ubuntu2_all.deb
167
168 This script will copy the file into the personal package management
169 environment and run dpkg with the -i (install) option.
170
171 Using Packages
172 --------------
173
174 Unlike most packages installed in the usual way by the root user, the installed
175 packages will not reside within a directory hierarchy rooted at / - the top of
176 the filesystem. Instead, they will reside in a location such as the following:
177
178 /home/me/.userinstall
179 /tmp/packages
180
181 (The precise location may be found by running the user-path script.)
182
183 Consequently, to make use of the installed software, it may be necessary to
184 edit your environment in a number of ways so that it may be located and
185 correctly loaded, initialised and executed.
186
187 Using Python Packages
188 ---------------------
189
190 Installed Python packages may be made available to Python by defining the
191 PYTHONPATH to include the directories usually searched by Python, but which
192 are actually located within the personal package management environment. For
193 example, with the Python 2.5 site-packages directory:
194
195 PYTHONPATH=`user-path /usr/lib/python2.5/site-packages/` python2.5
196
197 More complicated extension modules may require further adjustments to the
198 LD_LIBRARY_PATH and PYTHONPATH variables:
199
200 export LD_LIBRARY_PATH=`./user-path /usr/lib`
201 export PYTHONPATH=`./user-path /usr/lib/python2.5/site-packages/`
202 export PYTHONPATH=${PYTHONPATH}:`./user-path /var/lib/python-support/python2.5`
203
204 Entering the Package Manager
205 ----------------------------
206
207 It is also possible to administer the package manager from within the
208 installation:
209
210 user-enter
211
212 This should provide a "root" prompt which can then be used to issue commands
213 within the package manager environment. For example:
214
215 apt-get update
216
217 Constructing UML Instances
218 --------------------------
219
220 For some applications, it can be desirable to provide a completely isolated
221 environment for package installation and testing. This can be performed using
222 the User Mode Linux (UML) software.
223
224 To convert a package manager installation into a UML instance, start with the
225 uml-postsetup script which changes the installation's configuration in a
226 number of areas:
227
228 uml-postsetup
229
230 Then, as a privileged user, run the user-setupdev script to initialise some
231 UML-specific device files:
232
233 sudo uml-setupdev
234
235 Since UML needs to see its filesystems as images, not directories within an
236 existing filesystem, the uml-setupfs script needs to create these image files.
237 For example, to create a root filesystem 1GB in size, along with a swap file
238 512MB in size:
239
240 uml-setupfs 4 512
241
242 Again, as a privileged user, these images are then populated with the package
243 manager contents as follows:
244
245 uml-postsetupfs
246
247 NOTE: Add Linux build process.
248
249 Entering or Starting UML Instances
250 ----------------------------------
251
252 To enter a UML instance, use the uml-enter script:
253
254 uml-enter