1
.. IVLE - Informatics Virtual Learning Environment
2
Copyright (C) 2007-2009 The University of Melbourne
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.
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.
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
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
31
.. If this list changes, you also need to change the list below, and
32
the list in bin/ivle-dev-setup.
34
* Ubuntu 8.04 LTS 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
+ ConfigObj (``python-configobj``)
40
+ docutils (``python-docutils``)
41
+ epydoc (``python-epydoc``)
42
+ FormEncode (``python-formencode``)
43
+ Genshi (``python-genshi``)
44
+ psycopg2 (``python-psycopg2``)
45
+ pysvn (``python-svn``)
46
+ Storm (``python-storm``)
47
+ simplejson (``python-simplejson``, for Python 2.5 only)
48
* jQuery (``libjs-jquery``)
49
* CodeMirror (``libjs-codemirror``)
50
* PostgreSQL 8.3 or later (``postgresql``)
51
* Subversion (``subversion``)
52
* debootstrap (``debootstrap``)
54
* GCC and related build machinery (``build-essential``)
56
Master versus slave servers
57
===========================
59
IVLE is normally deployed in a cluster of several machines, split into
60
two different roles: master and slave.
62
There must be exactly one master server per cluster. The master normally
63
runs the PostgreSQL database server, the Subversion server, and the IVLE User
64
Management Server (``ivle-usrmgt-server``). It might also export shared data
65
directories to the slaves over NFS.
67
There may be any number of slaves in a cluster. They run the IVLE web
68
application, which also starts console host processes. Each slave makes use
69
of the shared services on the master.
71
For a small instance a slave may be run on the same machine as the master.
72
This is the setup described in the source installation section, while the
73
Ubuntu package installation section describes a multi-node configuration.
76
Installing from source
77
======================
79
When setting up a development IVLE environment on Ubuntu 10.04 LTS or later,
80
there are scripts to automate most of the process. First get and extract
81
`a release tarball <https://launchpad.net/ivle/+download>`_, or check out
82
the latest code from the Bazaar branch: ::
86
This will create a new directory, ``ivle``, containing a pristine
87
source tree. The remaining steps assume that you are in this new
90
One of IVLE's dependencies (``libjs-codemirror``) does not yet have an
91
official Ubuntu package. To make this dependency package available, add
92
the production PPA, and update your local package cache: ::
94
sudo add-apt-repository ppa:unimelb-ivle/production
97
Alternatively, manually obtain and install ``libjs-codemirror``.
103
The ``ivle-dev-setup`` script will configure PostgreSQL, Apache, IVLE
104
and the filesystem to cooperate, getting you most of the way to a
105
working system in just one step: ::
110
This reconfigures parts of your system, and has the potential to
111
break other applications using Apache or PostgreSQL. It may also
112
fail to execute if you have existing incompatible configurations
116
This may take a few minutes, and will ask you to confirm installation
117
of the dependency packages.
119
Upon completion, you must build a self-contained jail in which to run
120
untrusted user code. ``ivle-dev-setup`` will have configured most of
121
the necessary settings, but you may wish to use a local Ubuntu mirror
122
to improve speed or minimise download costs. If you don't wish to use
123
a special mirror, you may omit the first step. ::
125
sudo ivle-config --jail/mirror http://url.to.mirror/ubuntu
126
sudo ivle-buildjail -r
129
``ivle-buildjail`` will download a large volume of package data --
130
potentially some hundreds of megabytes.
132
``ivle-buildjail`` will download, unpack and install a minimal Ubuntu
133
system and configure it for IVLE usage. This could take a while.
135
Once the jail has been successfully built, IVLE is up and running,
136
but with no user accounts or other data in place. For development
137
or demonstration purposes, sample data (including fictitious users,
138
subjects, and projects) can be loaded.
140
For other environments, it may be more appropriate to start with an
141
empty database and just create users as required.
143
To load the sample data: ::
145
sudo ivle-loadsampledata examples/db/sample.sql
148
If you answer 'yes' to the ``ivle-loadsampledata`` prompt, any
149
existing data in your IVLE database will be **permanently
152
... or to add a new admin user: ::
154
sudo ivle-adduser --admin -p password username 'Full Name'
156
You should then be able to browse to http://ivle.localhost/, and
157
log in with username ``admin`` and password ``password``, or the
158
username and password that you gave to ``ivle-adduser``.
164
If the automatic installation scripts do not work, or if you want more
165
control over the whole process, these manual steps are probably for
166
you. But you need not read this section at all if you were able to log
167
in after following the steps above.
169
.. If this list changes, you also need to change the list above, and
170
the command in bin/ivle-dev-setup.
172
If you want to grab all of the required packages in one command, use::
174
sudo apt-get install apache2 libapache2-mod-python libapache2-svn \
175
python2.6 python-configobj python-docutils python-epydoc \
176
python-formencode python-genshi python-psycopg2 python-svn python-storm \
177
libjs-jquery libjs-codemirror postgresql subversion debootstrap rsync \
180
As IVLE needs to compile some binaries, you must first build, then
181
install it. From the source directory created earlier: ::
184
sudo ./setup.py install
188
Setting up the database
189
~~~~~~~~~~~~~~~~~~~~~~~
191
First, it is recommended that you create a separate database user for IVLE.
192
You may use any name for the user. ::
194
sudo -u postgres createuser ivleuser # Answer 'n' to all questions
195
sudo -u postgres psql -c "ALTER USER ivleuser WITH ENCRYPTED PASSWORD 'ivle-password';"
197
Now, you must create a PostgreSQL database, and populate it with the
198
IVLE schema. You may use any name for the database (here we use ``ivle``). ::
200
sudo -u postgres createdb -O ivleuser ivle
201
sudo -u postgres createlang plpgsql ivle
202
psql -h localhost -W ivle ivleuser < userdb/users.sql
204
The configuration wizard - ``ivle-config`` - will ask you a series of
205
questions. You should give the database username and password as configured
206
above. Apart from database settings, the defaults should be correct
207
for a development system. If deploying IVLE properly - particularly on
208
multiple nodes - several options will need to be changed. Watching
214
Creating the data tree
215
~~~~~~~~~~~~~~~~~~~~~~
217
IVLE needs a directory hierarchy in which to store filesystem data, which
218
by default lives in ``/var/lib/ivle``. Create it now. ::
220
sudo ivle-createdatadirs
223
Configuring the jail environment
224
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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).
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.
237
.. TODO: Move this around a bit, as the config options required differ for
238
the packaged version.
240
Now we can actually build the jail. The creation process basically downloads
241
a minimal Ubuntu system and installs it in ``/var/lib/ivle/jails/__base__``.
242
Note that this could download a couple of hundred megabytes. ::
244
sudo ivle-buildjail -r
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/.
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: ::
260
sudo a2ensite ivle-svn
261
sudo /etc/init.d/apache2 reload
264
Configuring hostname resolution
265
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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: ::
271
127.0.1.1 ivle.localhost public.ivle.localhost svn.ivle.localhost
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``: ::
276
127.0.1.1 svn.ivle.localhost
278
Then refresh the active copy of the jail: ::
283
Configuring the user management server
284
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
293
sudo /etc/init.d/ivle-usrmgt-server start
294
sudo update-rc.d ivle-usrmgt-server defaults 99
297
Creating the initial user
298
~~~~~~~~~~~~~~~~~~~~~~~~~
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``. ::
303
sudo ivle-adduser --admin -p PASSWORD USERNAME 'FULL NAME'
305
You should then be able to browse to http://ivle.localhost/, and
306
log in with that username and password.
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`.
312
For more advanced configuration, see :ref:`Configuring IVLE
313
<ref-configuring-ivle>`.
317
Installing from an Ubuntu package
318
=================================
320
IVLE is packaged in `a Launchpad PPA <https://launchpad.net/~unimelb-ivle/+archive/production>`_,
321
providing a more managed installation and upgrade mechanism than a source
324
These instructions document the process to install a production-ready
325
multi-node IVLE cluster. They expect that you have three domain names:
326
one for the main IVLE web UI, one for the Subversion service, and one
327
for serving user files publicly.
330
By design the public domain may have arbitrary user-generated content
331
served. Because of this, it should not have any domain with sensitive
332
cookies as a suffix, including the main IVLE web UI. Be very careful
333
with your choice here.
339
All master and slave nodes need to have access to the IVLE PPA.
340
`Visit it <https://launchpad.net/~unimelb-ivle/+archive/production>`_ and
341
follow the installation instructions on all involved systems.
347
Setting up the database server
348
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
350
The master server runs the central IVLE PostgreSQL database. ::
352
sudo apt-get install postgresql
354
Ubuntu's default PostgreSQL configuration doesn't permit remote access,
355
so we need to tweak it to allow password access from our slave. In
356
``/etc/postgresql/8.3/main/postgresql.conf``, find the ``listen_addresses``
357
option, and ensure it is set to ``*``. In
358
``/etc/postgresql/8.3/main/pg_hba.conf`` add a line like the following to the
359
end. This example will allow any host in the ``1.2.3.4/24`` subnet to
360
authenticate with a password as the ``ivle`` user to the ``ivle`` database. ::
362
host ivle ivle 1.2.3.4/24 md5
364
Then restart PostgreSQL, and the slaves should be able to see the database. ::
366
sudo /etc/init.d/postgresql-8.3 restart
369
Installing and configuring IVLE
370
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
372
We can now install IVLE. The installation process will ask you a few questons.
373
Answer that this host is a **master**, let it generate a random usrmgt-server
374
secret, elect to manage the database with ``dbconfig-common``, and use a
377
sudo apt-get install ivle
379
Once that's done, we have a couple of additional configuration items to set:
380
the URLs discussed earlier. Open up ``/etc/ivle/ivle.conf``,
381
and replace ``public.ivle.localhost`` and ``svn.ivle.localhost`` with the
382
correct domain names.
384
Make sure you restart the ``usrmgt-server`` afterwards, or newly created users
385
may inherit the old domain names. ::
387
sudo /etc/init.d/usrmgt-server restart
390
Sharing data between the servers
391
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
393
As well as its relational database, IVLE has a data hierarchy on the
394
fileystem. Two part of this (``/var/lib/ivle/jails`` and
395
``/var/lib/ivle/sessions``) must be shared between the master and all of the
396
slaves. It doesn't matter how you achieve this, but a reasonable method is
397
described here: exporting over NFS from the master.
399
We'll first create a tree (``/export/ivle`` in this example, but it can be
400
whatever you want) to be exported to the slaves, move the existing data
401
directories into it, and symlink them back into place. ::
403
sudo mkdir /export/ivle
404
sudo mv /var/lib/ivle/{sessions,jails} /export/ivle
405
sudo ln -s /export/ivle/{sessions,jails} /var/lib/ivle
407
Next install an NFS server. ::
409
sudo apt-get install nfs-kernel-server
411
Now we can export the directory we created earlier across the network.
412
Add something like the following line to ``/etc/exports``. ``someslave``
413
should be replaced with the hostname, IP address, or subnet of your
416
/export/ivle someslave(rw,sync)
418
Make sure you inform the kernel of the new export. ::
426
The master serves Subversion repositories through Apache on the Subversion
427
domain name that was discussed above. ::
429
sudo cp /usr/share/doc/ivle/apache-svn.conf /etc/apache2/sites-available/ivle-svn
430
sudo a2ensite ivle-svn
432
Edit ``/etc/apache2/sites-available/ivle-svn``, ensuring that the
433
``ServerName`` matches your chosen domain name. Then reload Apache's
436
sudo /etc/init.d/apache2 reload
439
Setting up a jail environment
440
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
442
IVLE requires that a base jail be provided, on top of which all of the
443
individual user jails are constructed in order to safely execute user code.
445
We need to change some configuration options before we can build a working
446
jail. First set the mirror and Ubuntu release -- make sure you replace the
447
URL and release code name with an Ubuntu mirror and your Ubuntu release. ::
449
sudo ivle-config --jail/mirror http://url.to.mirror/ubuntu --jail/suite hardy
451
Now comes the ugly bit: we need to tell the jail builder where to get the
452
IVLE code that must be present in the jail. If you're using the production
453
PPA, the following ``/etc/ivle/ivle.conf`` snippet will work. If you're not,
454
you'll have to replace the ``extra_keys`` and ``extra_sources`` values ::
458
-----BEGIN PGP PUBLIC KEY BLOCK-----
461
mI0ES2pQKAEEANiscebT7+SFnvpN8nABcwT5nEV6psUOF8CcIIrz3iv6b6wA3lYd0DzbD7RD
462
fs1MNriEHHgqPF6EUhGrkk1165Oqi+lULdjgL0Fzi3GFvLV9F8+BtL3wt3+MM7YC+aTS1nhF
463
dQcPpnhNAJagW5gR4dIc4w87sNquxgCdJeJn/N3XABEBAAG0KkxhdW5jaHBhZCBVbml2ZXJz
464
aXR5IG9mIE1lbGJvdXJuZSBJVkxFIFBQQYi2BBMBAgAgBQJLalAoAhsDBgsJCAcDAgQVAggD
465
BBYCAwECHgECF4AACgkQVwp7ATtnautCMgP8C6PbLNyx9akgbiwhakFfGaEbxGFCo1EAUE7v
466
FgdelJSEkeQLAn4WoANpixuojNi++PEDis22S4tz+ZC6G0dRU9Pcc1bb4xUgphR83QTcufH7
467
5EagfTf5lLIWaLdg5f/NeuHHrKvwKvPVkNJ3ShQejFB/xWGpqe2Rr7Rscm9lT0Q=
469
-----END PGP PUBLIC KEY BLOCK-----
471
extra_packages = ivle-services,
472
extra_sources = deb http://ppa.launchpad.net/unimelb-ivle/production/ubuntu hardy main,
474
Now we can build the jail. This will download lots of packages, and install
475
a minimal Ubuntu system in ``/var/lib/ivle/jails/__base__``. ::
477
sudo ivle-buildjail -r
479
You should now have a functional master.
482
Creating the initial user
483
~~~~~~~~~~~~~~~~~~~~~~~~~
485
The last master step for getting a usable IVLE set up is creating a user.
486
You'll probably want admin privileges - if not, drop the ``--admin``. ::
488
sudo ivle-adduser --admin -p PASSWORD USERNAME 'FULL NAME'
490
You can then visit your IVLE web UI domain and login in with the username
497
Installing and configuring IVLE
498
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
500
We need to tell the database configuration assistant that we want to connect
501
to a remote database. The second command will also ask you whether you want to
502
store administrative passwords: say no here. ::
504
sudo apt-get install dbconfig-common
505
sudo dpkg-reconfigure dbconfig-common
507
We are going to need some details from the master for authentication purposes.
508
Grab the ``password`` value from the ``database`` section, and the ``magic``
509
value from the ``usrmgt`` section of the master's ``/etc/ivle/ivle.conf``.
511
Now we can install IVLE. Advise the installer that this machine is not a
512
master, and use the details retrieved from the master to answer the rest of
515
sudo apt-get install ivle
517
Once the installation has completed, make the same configuration changes as on
518
the master: set the domain names in ``ivle.conf`` to real values.
520
For maximum performance, you should also set the ``version`` value in the
521
``media`` section. The exact string is not important, as long as the value is
522
identical on every slave, and changed on each upgrade. It is used to make
523
static file URLs unique, so clients can cache them indefinitely. The IVLE
524
version is conventionally used as this string.
527
Getting access to the shared data
528
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
530
We need to mount the shared components of the IVLE data hierarchy from the
531
master. If you've used the suggested method, follow these instructions.
532
Otherwise you'll have to work it out for yourself.
534
First install the NFS common utilities, required for NFS mounts. ::
536
sudo apt-get install nfs-common
538
Now we can add the mount to ``/etc/fstab``. Something like this should do: ::
540
themaster:/export/ivle /export/ivle nfs defaults 0 0
542
Then mount the filesystem, and link the shared directories into the
547
rmdir /var/lib/ivle/{sessions,jails}
548
ln -s /export/ivle/{sessions,jails} /var/lib/ivle
554
The slaves use Apache to serve the main IVLE web UI and public user files.
555
Let's activate the configuration now. ::
557
sudo cp /usr/share/doc/ivle/apache.conf /etc/apache2/sites-available/ivle
560
Now edit ``/etc/apache2/sites-available/ivle``, and ensure that the
561
``ServerName`` matches your chosen IVLE web UI domain name, and
562
``ServerAlias`` your public name. Then reload Apache's configuration. ::
564
sudo /etc/init.d/apache2 reload
added
removed
doc/man/install.rst
