← 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: William Grant
  • Date: 2012-06-28 01:52:02 UTC
  • Revision ID: me@williamgrant.id.au-20120628015202-f6ru7o367gt6nvgz
Hah

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/man/install.rst
31
31
.. If this list changes, you also need to change the list below, and
32
32
   the list in bin/ivle-dev-setup.
33
33
 
34
 
* Ubuntu 8.04 or later (other distros should work with some tweaking, but are untested)
 
34
* Ubuntu 8.04 LTS or later (other distros should work with some tweaking, but are untested)
35
35
* Apache 2.x (``apache2``) with modules:
36
36
   + mod_python (``libapache2-mod-python``)
37
37
   + mod_dav_svn and mod_authz_svn (``libapache2-svn``)
38
38
* Python 2.5 (``python2.5``) or 2.6 (``python2.6``) with modules:
39
 
   + cjson (``python-cjson``)
40
39
   + ConfigObj (``python-configobj``)
41
40
   + docutils (``python-docutils``)
42
41
   + epydoc (``python-epydoc``)
45
44
   + psycopg2 (``python-psycopg2``)
46
45
   + pysvn (``python-svn``)
47
46
   + Storm (``python-storm``)
 
47
   + simplejson (``python-simplejson``, for Python 2.5 only)
48
48
* jQuery (``libjs-jquery``)
 
49
* CodeMirror (``libjs-codemirror``)
49
50
* PostgreSQL 8.3 or later (``postgresql``)
50
51
* Subversion (``subversion``)
51
52
* debootstrap (``debootstrap``)
55
56
Master versus slave servers
56
57
===========================
57
58
 
58
 
Installing from a Debian package
59
 
================================
60
 
 
61
 
.. _database-setup:
 
59
IVLE is normally deployed in a cluster of several machines, split into
 
60
two different roles: master and slave.
 
61
 
 
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.
 
66
 
 
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.
 
70
 
 
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.
62
74
 
63
75
 
64
76
Installing from source
65
77
======================
66
78
 
67
 
When setting up a development IVLE environment on Ubuntu 9.04 or later,
 
79
When setting up a development IVLE environment on Ubuntu 10.04 LTS or later,
68
80
there are scripts to automate most of the process. First get and extract
69
 
a release, or check out the latest code from the bzr branch: ::
 
81
`a release tarball <https://launchpad.net/ivle/+download>`_, or check out
 
82
the latest code from the Bazaar branch: ::
70
83
 
71
84
   bzr get lp:ivle
72
85
 
74
87
source tree. The remaining steps assume that you are in this new
75
88
directory.
76
89
 
 
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: ::
 
93
 
 
94
   sudo add-apt-repository ppa:unimelb-ivle/production
 
95
   sudo apt-get update
 
96
 
 
97
Alternatively, manually obtain and install ``libjs-codemirror``.
 
98
 
 
99
 
 
100
Automated setup
 
101
---------------
 
102
 
77
103
The ``ivle-dev-setup`` script will configure PostgreSQL, Apache, IVLE
78
104
and the filesystem to cooperate, getting you most of the way to a
79
105
working system in just one step: ::
146
172
If you want to grab all of the required packages in one command, use::
147
173
 
148
174
    sudo apt-get install apache2 libapache2-mod-python libapache2-svn \
149
 
    python2.6 python-cjson python-configobj python-docutils python-epydoc \
 
175
    python2.6 python-configobj python-docutils python-epydoc \
150
176
    python-formencode python-genshi python-psycopg2 python-svn python-storm \
151
 
    libjs-jquery postgresql subversion debootstrap rsync build-essential
152
 
 
153
 
While installing from a distribution package is often a better idea for
154
 
users, developers will need to install from a plain source tree.
155
 
 
156
 
To get the tree, either grab and extract a release tarball, or get the
157
 
very latest code using bzr: ::
158
 
 
159
 
   bzr get lp:ivle
160
 
 
161
 
You should then change into the new source directory.
 
177
    libjs-jquery libjs-codemirror postgresql subversion debootstrap rsync \
 
178
    build-essential
162
179
 
163
180
As IVLE needs to compile some binaries, you must first build, then
164
 
install it: ::
 
181
install it. From the source directory created earlier: ::
165
182
 
166
183
   ./setup.py build
167
184
   sudo ./setup.py install
168
185
 
169
 
Unlike the package, you will have to manually set up the database and
170
 
configuration.
 
186
.. _database-setup:
 
187
 
 
188
Setting up the database
 
189
~~~~~~~~~~~~~~~~~~~~~~~
171
190
 
172
191
First, it is recommended that you create a separate database user for IVLE.
173
192
You may use any name for the user. ::
192
211
   sudo ivle-config
193
212
 
194
213
 
195
 
Basic configuration
196
 
===================
197
 
 
198
 
.. Note: Place here only the configuration required to get the system
199
 
   installed and running. Any further configuration should go in config.rst.
 
214
Creating the data tree
 
215
~~~~~~~~~~~~~~~~~~~~~~
200
216
 
201
217
IVLE needs a directory hierarchy in which to store filesystem data, which
202
218
by default lives in ``/var/lib/ivle``. Create it now. ::
205
221
 
206
222
 
207
223
Configuring the jail environment
208
 
--------------------------------
 
224
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
209
225
 
210
226
You will require a self-contained jail environment in which to safely
211
227
execute student code. 
217
233
   devmode = True
218
234
   suite = jaunty # Replace this with the codename of your Ubuntu release.
219
235
   mirror = http://url.to.archive/mirror # Replace with a fast Ubuntu mirror.
220
 
   extra_packages = python-configobj, python-svn, python-cjson
221
236
 
222
237
.. TODO: Move this around a bit, as the config options required differ for
223
238
   the packaged version.
228
243
 
229
244
   sudo ivle-buildjail -r
230
245
 
 
246
 
231
247
Configuring Apache
232
 
------------------
 
248
~~~~~~~~~~~~~~~~~~
233
249
 
234
250
IVLE makes use of two Apache virtual hosts: one for the application itself,
235
251
and one for the Subversion services. There are example configuration files
246
262
 
247
263
 
248
264
Configuring hostname resolution
249
 
--------------------------------
 
265
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
250
266
 
251
267
All of IVLE's hostnames need to be resolvable from the local system. For a
252
268
production environment, this would be done in DNS. For a development system,
265
281
 
266
282
 
267
283
Configuring the user management server
268
 
--------------------------------------
 
284
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
269
285
 
270
286
You need to have the IVLE user management server (``usrmgt-server``) running
271
287
for many parts of IVLE to operate properly, so it should be configured to
279
295
 
280
296
 
281
297
Creating the initial user
282
 
-------------------------
 
298
~~~~~~~~~~~~~~~~~~~~~~~~~
283
299
 
284
300
The final step in getting a usable IVLE set up is creating a user. You'll
285
301
probably want admin privileges - if not, drop the ``--admin``. ::
286
302
 
287
 
   sudo ivle-adduser --admin -p password username 'Full Name'
 
303
   sudo ivle-adduser --admin -p PASSWORD USERNAME 'FULL NAME'
288
304
 
289
305
You should then be able to browse to http://ivle.localhost/, and
290
306
log in with that username and password.
295
311
.. note::
296
312
   For more advanced configuration, see :ref:`Configuring IVLE
297
313
   <ref-configuring-ivle>`.
 
314
 
 
315
 
 
316
 
 
317
Installing from an Ubuntu package
 
318
=================================
 
319
 
 
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
 
322
installation.
 
323
 
 
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.
 
328
 
 
329
.. warning::
 
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.
 
334
 
 
335
 
 
336
Shared setup
 
337
------------
 
338
 
 
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.
 
342
 
 
343
 
 
344
Master setup
 
345
------------
 
346
 
 
347
Setting up the database server
 
348
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
349
 
 
350
The master server runs the central IVLE PostgreSQL database. ::
 
351
 
 
352
   sudo apt-get install postgresql
 
353
 
 
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. ::
 
361
 
 
362
   host    ivle        ivle        1.2.3.4/24      md5
 
363
 
 
364
Then restart PostgreSQL, and the slaves should be able to see the database. ::
 
365
 
 
366
   sudo /etc/init.d/postgresql-8.3 restart
 
367
 
 
368
 
 
369
Installing and configuring IVLE
 
370
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
371
 
 
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
 
375
random password. ::
 
376
 
 
377
   sudo apt-get install ivle
 
378
 
 
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.
 
383
 
 
384
Make sure you restart the ``usrmgt-server`` afterwards, or newly created users
 
385
may inherit the old domain names. ::
 
386
 
 
387
   sudo /etc/init.d/usrmgt-server restart
 
388
 
 
389
 
 
390
Sharing data between the servers
 
391
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
392
 
 
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.
 
398
 
 
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. ::
 
402
 
 
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
 
406
 
 
407
Next install an NFS server. ::
 
408
 
 
409
   sudo apt-get install nfs-kernel-server
 
410
 
 
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
 
414
slave(s). ::
 
415
 
 
416
   /export/ivle         someslave(rw,sync)
 
417
 
 
418
Make sure you inform the kernel of the new export. ::
 
419
 
 
420
   sudo exportfs -a
 
421
 
 
422
 
 
423
Configuring Apache
 
424
~~~~~~~~~~~~~~~~~~
 
425
 
 
426
The master serves Subversion repositories through Apache on the Subversion
 
427
domain name that was discussed above. ::
 
428
 
 
429
   sudo cp /usr/share/doc/ivle/apache-svn.conf /etc/apache2/sites-available/ivle-svn
 
430
   sudo a2ensite ivle-svn
 
431
 
 
432
Edit ``/etc/apache2/sites-available/ivle-svn``, ensuring that the
 
433
``ServerName`` matches your chosen domain name. Then reload Apache's
 
434
configuration. ::
 
435
 
 
436
   sudo /etc/init.d/apache2 reload
 
437
 
 
438
 
 
439
Setting up a jail environment
 
440
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
441
 
 
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.
 
444
 
 
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. ::
 
448
 
 
449
   sudo ivle-config --jail/mirror http://url.to.mirror/ubuntu --jail/suite hardy
 
450
 
 
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 ::
 
455
 
 
456
   [jail]
 
457
   extra_keys = '''
 
458
   -----BEGIN PGP PUBLIC KEY BLOCK-----
 
459
   Version: SKS 1.0.10
 
460
   
 
461
   mI0ES2pQKAEEANiscebT7+SFnvpN8nABcwT5nEV6psUOF8CcIIrz3iv6b6wA3lYd0DzbD7RD
 
462
   fs1MNriEHHgqPF6EUhGrkk1165Oqi+lULdjgL0Fzi3GFvLV9F8+BtL3wt3+MM7YC+aTS1nhF
 
463
   dQcPpnhNAJagW5gR4dIc4w87sNquxgCdJeJn/N3XABEBAAG0KkxhdW5jaHBhZCBVbml2ZXJz
 
464
   aXR5IG9mIE1lbGJvdXJuZSBJVkxFIFBQQYi2BBMBAgAgBQJLalAoAhsDBgsJCAcDAgQVAggD
 
465
   BBYCAwECHgECF4AACgkQVwp7ATtnautCMgP8C6PbLNyx9akgbiwhakFfGaEbxGFCo1EAUE7v
 
466
   FgdelJSEkeQLAn4WoANpixuojNi++PEDis22S4tz+ZC6G0dRU9Pcc1bb4xUgphR83QTcufH7
 
467
   5EagfTf5lLIWaLdg5f/NeuHHrKvwKvPVkNJ3ShQejFB/xWGpqe2Rr7Rscm9lT0Q=
 
468
   =TJYw
 
469
   -----END PGP PUBLIC KEY BLOCK-----
 
470
   '''
 
471
   extra_packages = ivle-services,
 
472
   extra_sources = deb http://ppa.launchpad.net/unimelb-ivle/production/ubuntu hardy main,
 
473
 
 
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__``. ::
 
476
 
 
477
   sudo ivle-buildjail -r
 
478
 
 
479
You should now have a functional master.
 
480
 
 
481
 
 
482
Creating the initial user
 
483
~~~~~~~~~~~~~~~~~~~~~~~~~
 
484
 
 
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``. ::
 
487
 
 
488
   sudo ivle-adduser --admin -p PASSWORD USERNAME 'FULL NAME'
 
489
 
 
490
You can then visit your IVLE web UI domain and login in with the username
 
491
and password.
 
492
 
 
493
 
 
494
Slave setup
 
495
-----------
 
496
 
 
497
Installing and configuring IVLE
 
498
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
499
 
 
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. ::
 
503
 
 
504
   sudo apt-get install dbconfig-common
 
505
   sudo dpkg-reconfigure dbconfig-common
 
506
 
 
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``.
 
510
 
 
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
 
513
the questions. ::
 
514
 
 
515
   sudo apt-get install ivle
 
516
 
 
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.
 
519
 
 
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.
 
525
 
 
526
 
 
527
Getting access to the shared data
 
528
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
529
 
 
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.
 
533
 
 
534
First install the NFS common utilities, required for NFS mounts. ::
 
535
 
 
536
   sudo apt-get install nfs-common
 
537
 
 
538
Now we can add the mount to ``/etc/fstab``. Something like this should do: ::
 
539
 
 
540
  themaster:/export/ivle /export/ivle nfs defaults 0 0
 
541
 
 
542
Then mount the filesystem, and link the shared directories into the
 
543
hierarchy. ::
 
544
 
 
545
   mount -a
 
546
   ivle-createdatadirs
 
547
   rmdir /var/lib/ivle/{sessions,jails}
 
548
   ln -s /export/ivle/{sessions,jails} /var/lib/ivle
 
549
 
 
550
 
 
551
Configuring Apache
 
552
~~~~~~~~~~~~~~~~~~
 
553
 
 
554
The slaves use Apache to serve the main IVLE web UI and public user files.
 
555
Let's activate the configuration now. ::
 
556
 
 
557
   sudo cp /usr/share/doc/ivle/apache.conf /etc/apache2/sites-available/ivle
 
558
   sudo a2ensite ivle
 
559
 
 
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. ::
 
563
 
 
564
   sudo /etc/init.d/apache2 reload