← 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: 2009-06-29 03:13:46 UTC
  • mto: This revision was merged to the branch mainline in revision 1322.
  • Revision ID: grantw@unimelb.edu.au-20090629031346-e94ca3asu6chpv1d
Add FormEncode to dependencies, and sort alphabetically.

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
************
 
19
Installation
 
20
************
 
21
 
 
22
System requirements
 
23
===================
 
24
 
 
25
Given versions are those on which IVLE is known to work; earlier versions
 
26
might work too. Debian/Ubuntu package names are given after the name of the
 
27
software.
 
28
 
 
29
* Ubuntu 8.04 or later (other distros should work with some tweaking, but are untested)
 
30
* Apache 2.x with modules:
 
31
   + mod_python (``libapache2-mod-python``)
 
32
   + mod_dav_svn and mod_authz_svn (``libapache2-svn``)
 
33
* Python 2.5 or 2.6 with modules:
 
34
   + cjson (``python-cjson``)
 
35
   + ConfigObj (``python-configobj``)
 
36
   + docutils (``python-docutils``)
 
37
   + epydoc (``python-epydoc``)
 
38
   + FormEncode (``python-formencode``)
 
39
   + Genshi (``python-genshi``)
 
40
   + psycopg2 (``python-psycopg2``)
 
41
   + pysvn (``python-svn``)
 
42
   + Routes (``python-routes``)
 
43
   + Storm (``python-storm``)
 
44
* jQuery (``libjs-jquery``)
 
45
* PostgreSQL 8.3 or later (``postgresql``)
 
46
* Subversion (``subversion``)
 
47
* debootstrap (``debootstrap``)
 
48
* GCC and related build machinery (``build-essential``)
 
49
 
 
50
Master versus slave servers
 
51
===========================
 
52
 
 
53
Installing from a Debian package
 
54
================================
 
55
 
 
56
Installing from source
 
57
======================
 
58
 
 
59
While installing from a distribution package is often a better idea for
 
60
users, developers will need to install from a plain source tree.
 
61
 
 
62
To get the tree, either grab and extract a release tarball, or get the
 
63
very latest code using bzr: ::
 
64
 
 
65
   bzr get lp:ivle
 
66
 
 
67
You should then change into the new source directory.
 
68
 
 
69
As IVLE needs to compile some binaries, you must first build, then
 
70
install it: ::
 
71
 
 
72
   ./setup.py build
 
73
   sudo ./setup.py install
 
74
 
 
75
Unlike the package, you will have to manually set up the database and
 
76
configuration.
 
77
 
 
78
.. TODO: Separate IVLE PostgreSQL account.
 
79
 
 
80
First you must create a PostgreSQL database, and populate it with the
 
81
IVLE schema. You may use any name for the database. ::
 
82
 
 
83
   sudo -u postgres createdb ivle
 
84
   sudo -u postgres createlang plpgsql ivle
 
85
   sudo -u postgres psql -d ivle < userdb/users.sql
 
86
 
 
87
The configuration wizard - ``ivle-config`` - will ask you a series of
 
88
questions. Apart from database settings, the defaults should be correct
 
89
for a development system. If deploying IVLE properly - particularly on
 
90
multiple nodes - several options will need to be changed. Watching
 
91
carefully, run: ::
 
92
 
 
93
   sudo ivle-config
 
94
 
 
95
 
 
96
Basic configuration
 
97
===================
 
98
 
 
99
.. Note: Place here only the configuration required to get the system
 
100
   installed and running. Any further configuration should go in config.rst.
 
101
 
 
102
IVLE needs a directory hierarchy in which to store filesystem data, which
 
103
by default lives in ``/var/lib/ivle``. Create it now. ::
 
104
 
 
105
   sudo ivle-createdatadirs
 
106
 
 
107
 
 
108
Configuring the jail environment
 
109
--------------------------------
 
110
 
 
111
You will require a self-contained jail environment in which to safely
 
112
execute student code. 
 
113
Before you can actually build the jail, a few configuration options are
 
114
needed. Open up ``/etc/ivle/ivle.conf``, and find the ``[jail]`` section.
 
115
Add to it: ::
 
116
 
 
117
   devmode = True
 
118
   suite = jaunty # Replace this with the codename of your Ubuntu release.
 
119
   mirror = http://url.to.archive/mirror # Replace with a fast Ubuntu mirror.
 
120
   extra_packages = python-configobj, python-svn, python-cjson
 
121
 
 
122
Now we can actually build the jail. The creation process basically downloads
 
123
a minimal Ubuntu system and installs it in ``/var/lib/ivle/jails/__base__``.
 
124
Note that this could download a couple of hundred megabytes. ::
 
125
 
 
126
   sudo ivle-buildjail -r
 
127
 
 
128
Configuring Apache
 
129
------------------
 
130
 
 
131
IVLE makes use of two Apache virtual hosts: one for the application itself,
 
132
and one for the Subversion services. There are example configuration files
 
133
in ``examples/config/apache.conf`` and ``examples/config/apache-svn.conf``,
 
134
which will run IVLE at ``http://ivle.localhost/``.
 
135
 
 
136
On a Debian or Ubuntu system, just copy those two files into
 
137
``/etc/apache2/sites-available`` under appropriate names (eg. ``ivle`` and
 
138
``ivle-svn``). Then you need to activate them: ::
 
139
 
 
140
   sudo a2ensite ivle
 
141
   sudo a2ensite ivle-svn
 
142
   sudo /etc/init.d/apache2 reload
 
143
 
 
144
 
 
145
Configuring hostname resolution
 
146
--------------------------------
 
147
 
 
148
All of IVLE's hostnames need to be resolvable from the local system. For a
 
149
production environment, this would be done in DNS. For a development system,
 
150
this is usually done in ``/etc/hosts``. Add this line to that file: ::
 
151
 
 
152
   127.0.1.1 ivle.localhost public.ivle.localhost svn.ivle.localhost
 
153
 
 
154
Code running inside the jail environment also needs to be able to resolve
 
155
those names. Add, to ``/var/lib/ivle/jails/__base_build__/etc/hosts``: ::
 
156
 
 
157
   127.0.1.1 svn.ivle.localhost
 
158
 
 
159
Then refresh the active copy of the jail: ::
 
160
 
 
161
   sudo ivle-buildjail
 
162
 
 
163
 
 
164
Configuring the user management server
 
165
--------------------------------------
 
166
 
 
167
You need to have the IVLE user management server (``usrmgt-server``) running
 
168
for many parts of IVLE to operate properly, so it should be configured to
 
169
start on boot. There is an example init script in
 
170
``examples/config/usrmgt-server.init``. For Debian or Ubuntu, copy it to
 
171
``/etc/init.d/ivle``. Start it now, and set it to start automatically: ::
 
172
 
 
173
   sudo /etc/init.d/usrmgt-server start
 
174
   sudo update-rc.d usrmgt-server defaults 99
 
175
 
 
176
.. note::
 
177
   For more advanced configuration, see :ref:`Configuring IVLE
 
178
   <ref-configuring-ivle>`.