← Back to branch summary

~azzar1/unity/add-show-desktop-key

« back to all changes in this revision

Viewing changes to doc/man/install.rst

  • Committer: mattgiuca
  • Date: 2008-01-25 06:20:32 UTC
  • Revision ID: svn-v3-trunk0:2b9c9e99-6f39-0410-b283-7f802c844ae2:trunk:313
test/test_framework: Updated examples, a bit of better descriptions, sample
    partial solutions, etc.

Added all sample subject material.
This has been copied from test/test_framework and modified slightly.
There is now a subject "sample" with 2 worksheets. The 1st worksheet has 3
exercises. These work in IVLE by default.

setup.py: Added code to install subjects into the designated directory. This
means that installing IVLE will result in the sample subjects being
immediately available.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/man/install.rst
1
 
.. IVLE - Informatics Virtual Learning Environment
2
 
   Copyright (C) 2007-2009 The University of Melbourne
3
 
 
4
 
.. This program is free software; you can redistribute it and/or modify
5
 
   it under the terms of the GNU General Public License as published by
6
 
   the Free Software Foundation; either version 2 of the License, or
7
 
   (at your option) any later version.
8
 
 
9
 
.. This program is distributed in the hope that it will be useful,
10
 
   but WITHOUT ANY WARRANTY; without even the implied warranty of
11
 
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12
 
   GNU General Public License for more details.
13
 
 
14
 
.. You should have received a copy of the GNU General Public License
15
 
   along with this program; if not, write to the Free Software
16
 
   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
17
 
 
18
 
.. _ref-install:
19
 
 
20
 
************
21
 
Installation
22
 
************
23
 
 
24
 
System requirements
25
 
===================
26
 
 
27
 
Given versions are those on which IVLE is known to work; earlier versions
28
 
might work too. Debian/Ubuntu package names are given after the name of the
29
 
software.
30
 
 
31
 
.. If this list changes, you also need to change the list below, and
32
 
   the list in bin/ivle-dev-setup.
33
 
 
34
 
* Ubuntu 8.04 or later (other distros should work with some tweaking, but are untested)
35
 
* Apache 2.x (``apache2``) with modules:
36
 
   + mod_python (``libapache2-mod-python``)
37
 
   + mod_dav_svn and mod_authz_svn (``libapache2-svn``)
38
 
* Python 2.5 (``python2.5``) or 2.6 (``python2.6``) with modules:
39
 
   + cjson (``python-cjson``)
40
 
   + ConfigObj (``python-configobj``)
41
 
   + docutils (``python-docutils``)
42
 
   + epydoc (``python-epydoc``)
43
 
   + FormEncode (``python-formencode``)
44
 
   + Genshi (``python-genshi``)
45
 
   + psycopg2 (``python-psycopg2``)
46
 
   + pysvn (``python-svn``)
47
 
   + Storm (``python-storm``)
48
 
* jQuery (``libjs-jquery``)
49
 
* PostgreSQL 8.3 or later (``postgresql``)
50
 
* Subversion (``subversion``)
51
 
* debootstrap (``debootstrap``)
52
 
* rsync (``rsync``)
53
 
* GCC and related build machinery (``build-essential``)
54
 
 
55
 
Master versus slave servers
56
 
===========================
57
 
 
58
 
IVLE is normally deployed in a cluster of several machines, split into
59
 
two different roles: master and slave.
60
 
 
61
 
There must be exactly one master server per cluster. The master normally
62
 
runs the PostgreSQL database server, the Subversion server, and the IVLE User
63
 
Management Server (``ivle-usrmgt-server``). It might also export shared data
64
 
directories to the slaves over NFS.
65
 
 
66
 
There may be any number of slaves in a cluster. They run the IVLE web
67
 
application, which also starts console host processes. Each slave makes use
68
 
of the shared services on the master.
69
 
 
70
 
For a small instance a slave may be run on the same machine as the master.
71
 
This is the setup described on this page.
72
 
 
73
 
 
74
 
Installing from a Debian package
75
 
================================
76
 
 
77
 
.. _database-setup:
78
 
 
79
 
 
80
 
Installing from source
81
 
======================
82
 
 
83
 
When setting up a development IVLE environment on Ubuntu 9.04 or later,
84
 
there are scripts to automate most of the process. First get and extract
85
 
a release, or check out the latest code from the bzr branch: ::
86
 
 
87
 
   bzr get lp:ivle
88
 
 
89
 
This will create a new directory, ``ivle``, containing a pristine
90
 
source tree. The remaining steps assume that you are in this new
91
 
directory.
92
 
 
93
 
The ``ivle-dev-setup`` script will configure PostgreSQL, Apache, IVLE
94
 
and the filesystem to cooperate, getting you most of the way to a
95
 
working system in just one step: ::
96
 
 
97
 
   bin/ivle-dev-setup
98
 
 
99
 
.. warning::
100
 
   This reconfigures parts of your system, and has the potential to
101
 
   break other applications using Apache or PostgreSQL. It may also
102
 
   fail to execute if you have existing incompatible configurations
103
 
   of those services.
104
 
   
105
 
 
106
 
This may take a few minutes, and will ask you to confirm installation
107
 
of the dependency packages.
108
 
 
109
 
Upon completion, you must build a self-contained jail in which to run
110
 
untrusted user code. ``ivle-dev-setup`` will have configured most of
111
 
the necessary settings, but you may wish to use a local Ubuntu mirror
112
 
to improve speed or minimise download costs. If you don't wish to use
113
 
a special mirror, you may omit the first step. ::
114
 
 
115
 
   sudo ivle-config --jail/mirror http://url.to.mirror/ubuntu
116
 
   sudo ivle-buildjail -r
117
 
 
118
 
.. warning::
119
 
   ``ivle-buildjail`` will download a large volume of package data --
120
 
   potentially some hundreds of megabytes.
121
 
 
122
 
``ivle-buildjail`` will download, unpack and install a minimal Ubuntu
123
 
system and configure it for IVLE usage. This could take a while.
124
 
 
125
 
Once the jail has been successfully built, IVLE is up and running,
126
 
but with no user accounts or other data in place. For development
127
 
or demonstration purposes, sample data (including fictitious users,
128
 
subjects, and projects) can be loaded.
129
 
 
130
 
For other environments, it may be more appropriate to start with an
131
 
empty database and just create users as required.
132
 
 
133
 
To load the sample data: ::
134
 
 
135
 
   sudo ivle-loadsampledata examples/db/sample.sql
136
 
 
137
 
.. warning::
138
 
   If you answer 'yes' to the ``ivle-loadsampledata`` prompt, any
139
 
   existing data in your IVLE database will be **permanently
140
 
   destroyed**.
141
 
 
142
 
... or to add a new admin user: ::
143
 
 
144
 
   sudo ivle-adduser --admin -p password username 'Full Name'
145
 
 
146
 
You should then be able to browse to http://ivle.localhost/, and
147
 
log in with username ``admin`` and password ``password``, or the
148
 
username and password that you gave to ``ivle-adduser``.
149
 
 
150
 
 
151
 
Manual steps
152
 
------------
153
 
 
154
 
If the automatic installation scripts do not work, or if you want more
155
 
control over the whole process, these manual steps are probably for
156
 
you. But you need not read this section at all if you were able to log
157
 
in after following the steps above.
158
 
 
159
 
.. If this list changes, you also need to change the list above, and
160
 
   the command in bin/ivle-dev-setup.
161
 
 
162
 
If you want to grab all of the required packages in one command, use::
163
 
 
164
 
    sudo apt-get install apache2 libapache2-mod-python libapache2-svn \
165
 
    python2.6 python-cjson python-configobj python-docutils python-epydoc \
166
 
    python-formencode python-genshi python-psycopg2 python-svn python-storm \
167
 
    libjs-jquery postgresql subversion debootstrap rsync build-essential
168
 
 
169
 
While installing from a distribution package is often a better idea for
170
 
users, developers will need to install from a plain source tree.
171
 
 
172
 
To get the tree, either grab and extract a release tarball, or get the
173
 
very latest code using bzr: ::
174
 
 
175
 
   bzr get lp:ivle
176
 
 
177
 
You should then change into the new source directory.
178
 
 
179
 
As IVLE needs to compile some binaries, you must first build, then
180
 
install it: ::
181
 
 
182
 
   ./setup.py build
183
 
   sudo ./setup.py install
184
 
 
185
 
Unlike the package, you will have to manually set up the database and
186
 
configuration.
187
 
 
188
 
First, it is recommended that you create a separate database user for IVLE.
189
 
You may use any name for the user. ::
190
 
 
191
 
   sudo -u postgres createuser ivleuser     # Answer 'n' to all questions
192
 
   sudo -u postgres psql -c "ALTER USER ivleuser WITH ENCRYPTED PASSWORD 'ivle-password';"
193
 
 
194
 
Now, you must create a PostgreSQL database, and populate it with the
195
 
IVLE schema. You may use any name for the database (here we use ``ivle``). ::
196
 
 
197
 
   sudo -u postgres createdb -O ivleuser ivle
198
 
   sudo -u postgres createlang plpgsql ivle
199
 
   psql -h localhost -W ivle ivleuser < userdb/users.sql
200
 
 
201
 
The configuration wizard - ``ivle-config`` - will ask you a series of
202
 
questions. You should give the database username and password as configured
203
 
above. Apart from database settings, the defaults should be correct
204
 
for a development system. If deploying IVLE properly - particularly on
205
 
multiple nodes - several options will need to be changed. Watching
206
 
carefully, run: ::
207
 
 
208
 
   sudo ivle-config
209
 
 
210
 
 
211
 
Basic configuration
212
 
===================
213
 
 
214
 
.. Note: Place here only the configuration required to get the system
215
 
   installed and running. Any further configuration should go in config.rst.
216
 
 
217
 
IVLE needs a directory hierarchy in which to store filesystem data, which
218
 
by default lives in ``/var/lib/ivle``. Create it now. ::
219
 
 
220
 
   sudo ivle-createdatadirs
221
 
 
222
 
 
223
 
Configuring the jail environment
224
 
--------------------------------
225
 
 
226
 
You will require a self-contained jail environment in which to safely
227
 
execute student code. 
228
 
Before you can actually build the jail, a few configuration options are
229
 
needed. Open up ``/etc/ivle/ivle.conf``, and find the ``[jail]`` section
230
 
(**not** the ``[[jails]]`` section).
231
 
Add to it: ::
232
 
 
233
 
   devmode = True
234
 
   suite = jaunty # Replace this with the codename of your Ubuntu release.
235
 
   mirror = http://url.to.archive/mirror # Replace with a fast Ubuntu mirror.
236
 
   extra_packages = python-configobj, python-svn, python-cjson
237
 
 
238
 
.. TODO: Move this around a bit, as the config options required differ for
239
 
   the packaged version.
240
 
 
241
 
Now we can actually build the jail. The creation process basically downloads
242
 
a minimal Ubuntu system and installs it in ``/var/lib/ivle/jails/__base__``.
243
 
Note that this could download a couple of hundred megabytes. ::
244
 
 
245
 
   sudo ivle-buildjail -r
246
 
 
247
 
Configuring Apache
248
 
------------------
249
 
 
250
 
IVLE makes use of two Apache virtual hosts: one for the application itself,
251
 
and one for the Subversion services. There are example configuration files
252
 
in ``examples/config/apache.conf`` and ``examples/config/apache-svn.conf``,
253
 
which will run IVLE at http://ivle.localhost/.
254
 
 
255
 
On a Debian or Ubuntu system, just copy those two files into
256
 
``/etc/apache2/sites-available`` under appropriate names (eg. ``ivle`` and
257
 
``ivle-svn``). Then you need to activate them: ::
258
 
 
259
 
   sudo a2ensite ivle
260
 
   sudo a2ensite ivle-svn
261
 
   sudo /etc/init.d/apache2 reload
262
 
 
263
 
 
264
 
Configuring hostname resolution
265
 
--------------------------------
266
 
 
267
 
All of IVLE's hostnames need to be resolvable from the local system. For a
268
 
production environment, this would be done in DNS. For a development system,
269
 
this is usually done in ``/etc/hosts``. Add this line to that file: ::
270
 
 
271
 
   127.0.1.1 ivle.localhost public.ivle.localhost svn.ivle.localhost
272
 
 
273
 
Code running inside the jail environment also needs to be able to resolve
274
 
those names. Add, to ``/var/lib/ivle/jails/__base_build__/etc/hosts``: ::
275
 
 
276
 
   127.0.1.1 svn.ivle.localhost
277
 
 
278
 
Then refresh the active copy of the jail: ::
279
 
 
280
 
   sudo ivle-buildjail
281
 
 
282
 
 
283
 
Configuring the user management server
284
 
--------------------------------------
285
 
 
286
 
You need to have the IVLE user management server (``usrmgt-server``) running
287
 
for many parts of IVLE to operate properly, so it should be configured to
288
 
start on boot. There is an example init script in
289
 
``examples/config/usrmgt-server.init``. For Debian or Ubuntu, copy it to
290
 
``/etc/init.d/ivle-usrmgt-server``. Start it now, and set it to start
291
 
automatically: ::
292
 
 
293
 
   sudo /etc/init.d/ivle-usrmgt-server start
294
 
   sudo update-rc.d ivle-usrmgt-server defaults 99
295
 
 
296
 
 
297
 
Creating the initial user
298
 
-------------------------
299
 
 
300
 
The final step in getting a usable IVLE set up is creating a user. You'll
301
 
probably want admin privileges - if not, drop the ``--admin``. ::
302
 
 
303
 
   sudo ivle-adduser --admin -p password username 'Full Name'
304
 
 
305
 
You should then be able to browse to http://ivle.localhost/, and
306
 
log in with that username and password.
307
 
 
308
 
*Alternatively*, you may wish to import the IVLE sample data, for a complete
309
 
working IVLE environment (not for production use). See :ref:`sample-data`.
310
 
 
311
 
.. note::
312
 
   For more advanced configuration, see :ref:`Configuring IVLE
313
 
   <ref-configuring-ivle>`.