55
55
Master versus slave servers
56
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 in the source installation section, while the
72
Ubuntu package installation section describes a multi-node configuration.
58
Installing from a Debian package
59
================================
75
63
Installing from source
76
64
======================
78
When setting up a development IVLE environment on Ubuntu 9.04 or later,
79
there are scripts to automate most of the process. First get and extract
80
`a release tarball <https://launchpad.net/ivle/+download>`_, or check out
81
the latest code from the Bazaar branch: ::
85
This will create a new directory, ``ivle``, containing a pristine
86
source tree. The remaining steps assume that you are in this new
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: ::
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
106
This may take a few minutes, and will ask you to confirm installation
107
of the dependency packages.
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. ::
115
sudo ivle-config --jail/mirror http://url.to.mirror/ubuntu
116
sudo ivle-buildjail -r
119
``ivle-buildjail`` will download a large volume of package data --
120
potentially some hundreds of megabytes.
122
``ivle-buildjail`` will download, unpack and install a minimal Ubuntu
123
system and configure it for IVLE usage. This could take a while.
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.
130
For other environments, it may be more appropriate to start with an
131
empty database and just create users as required.
133
To load the sample data: ::
135
sudo ivle-loadsampledata examples/db/sample.sql
138
If you answer 'yes' to the ``ivle-loadsampledata`` prompt, any
139
existing data in your IVLE database will be **permanently
142
... or to add a new admin user: ::
144
sudo ivle-adduser --admin -p password username 'Full Name'
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``.
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.
159
.. If this list changes, you also need to change the list above, and
160
the command in bin/ivle-dev-setup.
66
.. If this list changes, you also need to change the list above.
162
68
If you want to grab all of the required packages in one command, use::
164
70
sudo apt-get install apache2 libapache2-mod-python libapache2-svn \
165
71
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
72
python-formencode python-genshi python-psycopg2 python-svn python-routes \
73
python-storm libjs-jquery postgresql subversion debootstrap rsync \
76
While installing from a distribution package is often a better idea for
77
users, developers will need to install from a plain source tree.
79
To get the tree, either grab and extract a release tarball, or get the
80
very latest code using bzr: ::
84
You should then change into the new source directory.
169
86
As IVLE needs to compile some binaries, you must first build, then
170
install it. From the source directory created earlier: ::
173
90
sudo ./setup.py install
177
Setting up the database
178
~~~~~~~~~~~~~~~~~~~~~~~
92
Unlike the package, you will have to manually set up the database and
180
95
First, it is recommended that you create a separate database user for IVLE.
181
96
You may use any name for the user. ::
286
204
Creating the initial user
287
~~~~~~~~~~~~~~~~~~~~~~~~~
205
-------------------------
289
207
The final step in getting a usable IVLE set up is creating a user. You'll
290
208
probably want admin privileges - if not, drop the ``--admin``. ::
292
sudo ivle-adduser --admin -p PASSWORD USERNAME 'FULL NAME'
210
sudo ivle-adduser --admin -p password username 'Full Name'
294
You should then be able to browse to http://ivle.localhost/, and
212
You should then be able to browse to ``http://ivle.localhost/``, and
295
213
log in with that username and password.
297
*Alternatively*, you may wish to import the IVLE sample data, for a complete
298
working IVLE environment (not for production use). See :ref:`sample-data`.
301
216
For more advanced configuration, see :ref:`Configuring IVLE
302
217
<ref-configuring-ivle>`.
306
Installing from an Ubuntu package
307
=================================
309
IVLE is packaged in `a Launchpad PPA <https://launchpad.net/~unimelb-ivle/+archive/production>`_,
310
providing a more managed installation and upgrade mechanism than a source
313
These instructions document the process to install a production-ready
314
multi-node IVLE cluster. They expect that you have three domain names:
315
one for the main IVLE web UI, one for the Subversion service, and one
316
for serving user files publicly.
319
By design the public domain may have arbitrary user-generated content
320
served. Because of this, it should not have any domain with sensitive
321
cookies as a suffix, including the main IVLE web UI. Be very careful
322
with your choice here.
328
All master and slave nodes need to have access to the IVLE PPA.
329
`Visit it <https://launchpad.net/~unimelb-ivle/+archive/production>`_ and
330
follow the installation instructions on all involved systems.
336
Setting up the database server
337
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
339
The master server runs the central IVLE PostgreSQL database. ::
341
sudo apt-get install postgresql
343
Ubuntu's default PostgreSQL configuration doesn't permit remote access,
344
so we need to tweak it to allow password access from our slave. In
345
``/etc/postgresql/8.3/main/postgresql.conf``, find the ``listen_addresses``
346
option, and ensure it is set to ``*``. In
347
``/etc/postgresql/8.3/main/pg_hba.conf`` add a line like the following to the
348
end. This example will allow any host in the ``1.2.3.4/24`` subnet to
349
authenticate with a password as the ``ivle`` user to the ``ivle`` database. ::
351
host ivle ivle 1.2.3.4/24 md5
353
Then restart PostgreSQL, and the slaves should be able to see the database. ::
355
sudo /etc/init.d/postgresql-8.3 restart
358
Installing and configuring IVLE
359
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
361
We can now install IVLE. The installation process will ask you a few questons.
362
Answer that this host is a **master**, let it generate a random usrmgt-server
363
secret, elect to manage the database with ``dbconfig-common``, and use a
366
sudo apt-get install ivle
368
Once that's done, we have a couple of additional configuration items to set:
369
the URLs discussed earlier. Open up ``/etc/ivle/ivle.conf``,
370
and replace ``public.ivle.localhost`` and ``svn.ivle.localhost`` with the
371
correct domain names.
373
Make sure you restart the ``usrmgt-server`` afterwards, or newly created users
374
may inherit the old domain names. ::
376
sudo /etc/init.d/usrmgt-server restart
379
Sharing data between the servers
380
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
382
As well as its relational database, IVLE has a data hierarchy on the
383
fileystem. Two part of this (``/var/lib/ivle/jails`` and
384
``/var/lib/ivle/sessions``) must be shared between the master and all of the
385
slaves. It doesn't matter how you achieve this, but a reasonable method is
386
described here: exporting over NFS from the master.
388
We'll first create a tree (``/export/ivle`` in this example, but it can be
389
whatever you want) to be exported to the slaves, move the existing data
390
directories into it, and symlink them back into place. ::
392
sudo mkdir /export/ivle
393
sudo mv /var/lib/ivle/{sessions,jails} /export/ivle
394
sudo ln -s /export/ivle/{sessions,jails} /var/lib/ivle
396
Next install an NFS server. ::
398
sudo apt-get install nfs-kernel-server
400
Now we can export the directory we created earlier across the network.
401
Add something like the following line to ``/etc/exports``. ``someslave``
402
should be replaced with the hostname, IP address, or subnet of your
405
/export/ivle someslave(rw,sync)
407
Make sure you inform the kernel of the new export. ::
415
The master serves Subversion repositories through Apache on the Subversion
416
domain name that was discussed above. ::
418
sudo cp /usr/share/doc/ivle/apache-svn.conf /etc/apache2/sites-available/ivle-svn
419
sudo a2ensite ivle-svn
421
Edit ``/etc/apache2/sites-available/ivle-svn``, ensuring that the
422
``ServerName`` matches your chosen domain name. Then reload Apache's
425
sudo /etc/init.d/apache2 reload
428
Setting up a jail environment
429
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
431
IVLE requires that a base jail be provided, on top of which all of the
432
individual user jails are constructed in order to safely execute user code.
434
We need to change some configuration options before we can build a working
435
jail. First set the mirror and Ubuntu release -- make sure you replace the
436
URL and release code name with an Ubuntu mirror and your Ubuntu release. ::
438
sudo ivle-config --jail/mirror http://url.to.mirror/ubuntu --jail/suite hardy
440
Now comes the ugly bit: we need to tell the jail builder where to get the
441
IVLE code that must be present in the jail. If you're using the production
442
PPA, the following ``/etc/ivle/ivle.conf`` snippet will work. If you're not,
443
you'll have to replace the ``extra_keys`` and ``extra_sources`` values ::
447
-----BEGIN PGP PUBLIC KEY BLOCK-----
450
mI0ES2pQKAEEANiscebT7+SFnvpN8nABcwT5nEV6psUOF8CcIIrz3iv6b6wA3lYd0DzbD7RD
451
fs1MNriEHHgqPF6EUhGrkk1165Oqi+lULdjgL0Fzi3GFvLV9F8+BtL3wt3+MM7YC+aTS1nhF
452
dQcPpnhNAJagW5gR4dIc4w87sNquxgCdJeJn/N3XABEBAAG0KkxhdW5jaHBhZCBVbml2ZXJz
453
aXR5IG9mIE1lbGJvdXJuZSBJVkxFIFBQQYi2BBMBAgAgBQJLalAoAhsDBgsJCAcDAgQVAggD
454
BBYCAwECHgECF4AACgkQVwp7ATtnautCMgP8C6PbLNyx9akgbiwhakFfGaEbxGFCo1EAUE7v
455
FgdelJSEkeQLAn4WoANpixuojNi++PEDis22S4tz+ZC6G0dRU9Pcc1bb4xUgphR83QTcufH7
456
5EagfTf5lLIWaLdg5f/NeuHHrKvwKvPVkNJ3ShQejFB/xWGpqe2Rr7Rscm9lT0Q=
458
-----END PGP PUBLIC KEY BLOCK-----
460
extra_packages = ivle-services,
461
extra_sources = deb http://ppa.launchpad.net/unimelb-ivle/production/ubuntu hardy main,
463
Now we can build the jail. This will download lots of packages, and install
464
a minimal Ubuntu system in ``/var/lib/ivle/jails/__base__``. ::
466
sudo ivle-buildjail -r
468
You should now have a functional master.
471
Creating the initial user
472
~~~~~~~~~~~~~~~~~~~~~~~~~
474
The last master step for getting a usable IVLE set up is creating a user.
475
You'll probably want admin privileges - if not, drop the ``--admin``. ::
477
sudo ivle-adduser --admin -p PASSWORD USERNAME 'FULL NAME'
479
You can then visit your IVLE web UI domain and login in with the username
486
Installing and configuring IVLE
487
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
489
We need to tell the database configuration assistant that we want to connect
490
to a remote database. The second command will also ask you whether you want to
491
store administrative passwords: say no here. ::
493
sudo apt-get install dbconfig-common
494
sudo dpkg-reconfigure dbconfig-common
496
We are going to need some details from the master for authentication purposes.
497
Grab the ``password`` value from the ``database`` section, and the ``magic``
498
value from the ``usrmgt`` section of the master's ``/etc/ivle/ivle.conf``.
500
Now we can install IVLE. Advise the installer that this machine is not a
501
master, and use the details retrieved from the master to answer the rest of
504
sudo apt-get install ivle
506
Once the installation has completed, make the same configuration changes as on
507
the master: set the domain names in ``ivle.conf`` to real values.
509
For maximum performance, you should also set the ``version`` value in the
510
``media`` section. The exact string is not important, as long as the value is
511
identical on every slave, and changed on each upgrade. It is used to make
512
static file URLs unique, so clients can cache them indefinitely. The IVLE
513
version is conventionally used as this string.
516
Getting access to the shared data
517
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
519
We need to mount the shared components of the IVLE data hierarchy from the
520
master. If you've used the suggested method, follow these instructions.
521
Otherwise you'll have to work it out for yourself.
523
First install the NFS common utilities, required for NFS mounts. ::
525
sudo apt-get install nfs-common
527
Now we can add the mount to ``/etc/fstab``. Something like this should do: ::
529
themaster:/export/ivle /export/ivle nfs defaults 0 0
531
Then mount the filesystem, and link the shared directories into the
536
rmdir /var/lib/ivle/{sessions,jails}
537
ln -s /export/ivle/{sessions,jails} /var/lib/ivle
543
The slaves use Apache to serve the main IVLE web UI and public user files.
544
Let's activate the configuration now. ::
546
sudo cp /usr/share/doc/ivle/apache.conf /etc/apache2/sites-available/ivle
549
Now edit ``/etc/apache2/sites-available/ivle``, and ensure that the
550
``ServerName`` matches your chosen IVLE web UI domain name, and
551
``ServerAlias`` your public name. Then reload Apache's configuration. ::
553
sudo /etc/init.d/apache2 reload
added
removed
doc/man/install.rst
