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 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``)
53
* GCC and related build machinery (``build-essential``)
55
Master versus slave servers
56
===========================
58
IVLE is normally deployed in a cluster of several machines, split into
59
two different roles: master and slave.
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.
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.
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.
74
Installing from a Debian package
75
================================
80
Installing from source
81
======================
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 tarball <https://launchpad.net/ivle/+download>`, or check out
86
the latest code from the Bazaar branch: ::
90
This will create a new directory, ``ivle``, containing a pristine
91
source tree. The remaining steps assume that you are in this new
98
The ``ivle-dev-setup`` script will configure PostgreSQL, Apache, IVLE
99
and the filesystem to cooperate, getting you most of the way to a
100
working system in just one step: ::
105
This reconfigures parts of your system, and has the potential to
106
break other applications using Apache or PostgreSQL. It may also
107
fail to execute if you have existing incompatible configurations
111
This may take a few minutes, and will ask you to confirm installation
112
of the dependency packages.
114
Upon completion, you must build a self-contained jail in which to run
115
untrusted user code. ``ivle-dev-setup`` will have configured most of
116
the necessary settings, but you may wish to use a local Ubuntu mirror
117
to improve speed or minimise download costs. If you don't wish to use
118
a special mirror, you may omit the first step. ::
120
sudo ivle-config --jail/mirror http://url.to.mirror/ubuntu
121
sudo ivle-buildjail -r
124
``ivle-buildjail`` will download a large volume of package data --
125
potentially some hundreds of megabytes.
127
``ivle-buildjail`` will download, unpack and install a minimal Ubuntu
128
system and configure it for IVLE usage. This could take a while.
130
Once the jail has been successfully built, IVLE is up and running,
131
but with no user accounts or other data in place. For development
132
or demonstration purposes, sample data (including fictitious users,
133
subjects, and projects) can be loaded.
135
For other environments, it may be more appropriate to start with an
136
empty database and just create users as required.
138
To load the sample data: ::
140
sudo ivle-loadsampledata examples/db/sample.sql
143
If you answer 'yes' to the ``ivle-loadsampledata`` prompt, any
144
existing data in your IVLE database will be **permanently
147
... or to add a new admin user: ::
149
sudo ivle-adduser --admin -p password username 'Full Name'
151
You should then be able to browse to http://ivle.localhost/, and
152
log in with username ``admin`` and password ``password``, or the
153
username and password that you gave to ``ivle-adduser``.
159
If the automatic installation scripts do not work, or if you want more
160
control over the whole process, these manual steps are probably for
161
you. But you need not read this section at all if you were able to log
162
in after following the steps above.
164
.. If this list changes, you also need to change the list above, and
165
the command in bin/ivle-dev-setup.
167
If you want to grab all of the required packages in one command, use::
169
sudo apt-get install apache2 libapache2-mod-python libapache2-svn \
170
python2.6 python-cjson python-configobj python-docutils python-epydoc \
171
python-formencode python-genshi python-psycopg2 python-svn python-storm \
172
libjs-jquery postgresql subversion debootstrap rsync build-essential
174
As IVLE needs to compile some binaries, you must first build, then
175
install it. From the source directory created earlier: ::
178
sudo ./setup.py install
181
Setting up the database
182
~~~~~~~~~~~~~~~~~~~~~~~
184
First, it is recommended that you create a separate database user for IVLE.
185
You may use any name for the user. ::
187
sudo -u postgres createuser ivleuser # Answer 'n' to all questions
188
sudo -u postgres psql -c "ALTER USER ivleuser WITH ENCRYPTED PASSWORD 'ivle-password';"
190
Now, you must create a PostgreSQL database, and populate it with the
191
IVLE schema. You may use any name for the database (here we use ``ivle``). ::
193
sudo -u postgres createdb -O ivleuser ivle
194
sudo -u postgres createlang plpgsql ivle
195
psql -h localhost -W ivle ivleuser < userdb/users.sql
197
The configuration wizard - ``ivle-config`` - will ask you a series of
198
questions. You should give the database username and password as configured
199
above. Apart from database settings, the defaults should be correct
200
for a development system. If deploying IVLE properly - particularly on
201
multiple nodes - several options will need to be changed. Watching
207
Creating the data tree
208
~~~~~~~~~~~~~~~~~~~~~~
210
IVLE needs a directory hierarchy in which to store filesystem data, which
211
by default lives in ``/var/lib/ivle``. Create it now. ::
213
sudo ivle-createdatadirs
216
Configuring the jail environment
217
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
219
You will require a self-contained jail environment in which to safely
220
execute student code.
221
Before you can actually build the jail, a few configuration options are
222
needed. Open up ``/etc/ivle/ivle.conf``, and find the ``[jail]`` section
223
(**not** the ``[[jails]]`` section).
227
suite = jaunty # Replace this with the codename of your Ubuntu release.
228
mirror = http://url.to.archive/mirror # Replace with a fast Ubuntu mirror.
229
extra_packages = python-configobj, python-svn, python-cjson
231
.. TODO: Move this around a bit, as the config options required differ for
232
the packaged version.
234
Now we can actually build the jail. The creation process basically downloads
235
a minimal Ubuntu system and installs it in ``/var/lib/ivle/jails/__base__``.
236
Note that this could download a couple of hundred megabytes. ::
238
sudo ivle-buildjail -r
244
IVLE makes use of two Apache virtual hosts: one for the application itself,
245
and one for the Subversion services. There are example configuration files
246
in ``examples/config/apache.conf`` and ``examples/config/apache-svn.conf``,
247
which will run IVLE at http://ivle.localhost/.
249
On a Debian or Ubuntu system, just copy those two files into
250
``/etc/apache2/sites-available`` under appropriate names (eg. ``ivle`` and
251
``ivle-svn``). Then you need to activate them: ::
254
sudo a2ensite ivle-svn
255
sudo /etc/init.d/apache2 reload
258
Configuring hostname resolution
259
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
261
All of IVLE's hostnames need to be resolvable from the local system. For a
262
production environment, this would be done in DNS. For a development system,
263
this is usually done in ``/etc/hosts``. Add this line to that file: ::
265
127.0.1.1 ivle.localhost public.ivle.localhost svn.ivle.localhost
267
Code running inside the jail environment also needs to be able to resolve
268
those names. Add, to ``/var/lib/ivle/jails/__base_build__/etc/hosts``: ::
270
127.0.1.1 svn.ivle.localhost
272
Then refresh the active copy of the jail: ::
277
Configuring the user management server
278
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
280
You need to have the IVLE user management server (``usrmgt-server``) running
281
for many parts of IVLE to operate properly, so it should be configured to
282
start on boot. There is an example init script in
283
``examples/config/usrmgt-server.init``. For Debian or Ubuntu, copy it to
284
``/etc/init.d/ivle-usrmgt-server``. Start it now, and set it to start
287
sudo /etc/init.d/ivle-usrmgt-server start
288
sudo update-rc.d ivle-usrmgt-server defaults 99
291
Creating the initial user
292
~~~~~~~~~~~~~~~~~~~~~~~~~
294
The final step in getting a usable IVLE set up is creating a user. You'll
295
probably want admin privileges - if not, drop the ``--admin``. ::
297
sudo ivle-adduser --admin -p password username 'Full Name'
299
You should then be able to browse to http://ivle.localhost/, and
300
log in with that username and password.
302
*Alternatively*, you may wish to import the IVLE sample data, for a complete
303
working IVLE environment (not for production use). See :ref:`sample-data`.
306
For more advanced configuration, see :ref:`Configuring IVLE
307
<ref-configuring-ivle>`.
added
removed
doc/man/install.rst
