← 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-12-08 03:50:24 UTC
  • mfrom: (1294.2.143 ui-the-third)
  • Revision ID: grantw@unimelb.edu.au-20091208035024-wjx8zp54gth15ph8
Merge ui-the-third. This is another UI revamp.

The header is now thin! Thin! The yellow bar is gone. The tabs are gone.
Breadcrumbs are here. Routes is replaced (with an object publishing
mechanism). Views are less repetitive. etc.

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
.. _ref-install:
 
19
 
 
20
************
 
21
Installation
 
22
************
 
23
 
 
24
System requirements
 
25
===================
 
26
 
 
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
 
29
software.
 
30
 
 
31
.. If this list changes, you also need to change the list below.
 
32
 
 
33
* Ubuntu 8.04 or later (other distros should work with some tweaking, but are untested)
 
34
* Apache 2.x (``apache2``) with modules:
 
35
   + mod_python (``libapache2-mod-python``)
 
36
   + mod_dav_svn and mod_authz_svn (``libapache2-svn``)
 
37
* Python 2.5 (``python2.5``) or 2.6 (``python2.6``) with modules:
 
38
   + cjson (``python-cjson``)
 
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
   + Routes (``python-routes``)
 
47
   + Storm (``python-storm``)
 
48
* jQuery (``libjs-jquery``)
 
49
* PostgreSQL 8.3 or later (``postgresql``)
 
50
* Subversion (``subversion``)
 
51
* debootstrap (``debootstrap``)
 
52
* rsync (``rsync``)
 
53
* GCC and related build machinery (``build-essential``)
 
54
 
 
55
Master versus slave servers
 
56
===========================
 
57
 
 
58
Installing from a Debian package
 
59
================================
 
60
 
 
61
.. _database-setup:
 
62
 
 
63
Installing from source
 
64
======================
 
65
 
 
66
.. If this list changes, you also need to change the list above.
 
67
 
 
68
If you want to grab all of the required packages in one command, use::
 
69
 
 
70
    sudo apt-get install apache2 libapache2-mod-python libapache2-svn \
 
71
    python2.6 python-cjson python-configobj python-docutils python-epydoc \
 
72
    python-formencode python-genshi python-psycopg2 python-svn python-routes \
 
73
    python-storm libjs-jquery postgresql subversion debootstrap rsync \
 
74
    build-essential
 
75
 
 
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.
 
78
 
 
79
To get the tree, either grab and extract a release tarball, or get the
 
80
very latest code using bzr: ::
 
81
 
 
82
   bzr get lp:ivle
 
83
 
 
84
You should then change into the new source directory.
 
85
 
 
86
As IVLE needs to compile some binaries, you must first build, then
 
87
install it: ::
 
88
 
 
89
   ./setup.py build
 
90
   sudo ./setup.py install
 
91
 
 
92
Unlike the package, you will have to manually set up the database and
 
93
configuration.
 
94
 
 
95
First, it is recommended that you create a separate database user for IVLE.
 
96
You may use any name for the user. ::
 
97
 
 
98
   sudo -u postgres createuser ivleuser     # Answer 'n' to all questions
 
99
   sudo -u postgres psql -c "ALTER USER ivleuser WITH ENCRYPTED PASSWORD 'ivle-password';"
 
100
 
 
101
Now, you must create a PostgreSQL database, and populate it with the
 
102
IVLE schema. You may use any name for the database (here we use ``ivle``). ::
 
103
 
 
104
   sudo -u postgres createdb -O ivleuser ivle
 
105
   sudo -u postgres createlang plpgsql ivle
 
106
   psql -h localhost -W ivle ivleuser < userdb/users.sql
 
107
 
 
108
The configuration wizard - ``ivle-config`` - will ask you a series of
 
109
questions. You should give the database username and password as configured
 
110
above. Apart from database settings, the defaults should be correct
 
111
for a development system. If deploying IVLE properly - particularly on
 
112
multiple nodes - several options will need to be changed. Watching
 
113
carefully, run: ::
 
114
 
 
115
   sudo ivle-config
 
116
 
 
117
 
 
118
Basic configuration
 
119
===================
 
120
 
 
121
.. Note: Place here only the configuration required to get the system
 
122
   installed and running. Any further configuration should go in config.rst.
 
123
 
 
124
IVLE needs a directory hierarchy in which to store filesystem data, which
 
125
by default lives in ``/var/lib/ivle``. Create it now. ::
 
126
 
 
127
   sudo ivle-createdatadirs
 
128
 
 
129
 
 
130
Configuring the jail environment
 
131
--------------------------------
 
132
 
 
133
You will require a self-contained jail environment in which to safely
 
134
execute student code. 
 
135
Before you can actually build the jail, a few configuration options are
 
136
needed. Open up ``/etc/ivle/ivle.conf``, and find the ``[jail]`` section
 
137
(**not** the ``[[jails]]`` section).
 
138
Add to it: ::
 
139
 
 
140
   devmode = True
 
141
   suite = jaunty # Replace this with the codename of your Ubuntu release.
 
142
   mirror = http://url.to.archive/mirror # Replace with a fast Ubuntu mirror.
 
143
   extra_packages = python-configobj, python-svn, python-cjson
 
144
 
 
145
.. TODO: Move this around a bit, as the config options required differ for
 
146
   the packaged version.
 
147
 
 
148
Now we can actually build the jail. The creation process basically downloads
 
149
a minimal Ubuntu system and installs it in ``/var/lib/ivle/jails/__base__``.
 
150
Note that this could download a couple of hundred megabytes. ::
 
151
 
 
152
   sudo ivle-buildjail -r
 
153
 
 
154
Configuring Apache
 
155
------------------
 
156
 
 
157
IVLE makes use of two Apache virtual hosts: one for the application itself,
 
158
and one for the Subversion services. There are example configuration files
 
159
in ``examples/config/apache.conf`` and ``examples/config/apache-svn.conf``,
 
160
which will run IVLE at ``http://ivle.localhost/``.
 
161
 
 
162
On a Debian or Ubuntu system, just copy those two files into
 
163
``/etc/apache2/sites-available`` under appropriate names (eg. ``ivle`` and
 
164
``ivle-svn``). Then you need to activate them: ::
 
165
 
 
166
   sudo a2ensite ivle
 
167
   sudo a2ensite ivle-svn
 
168
   sudo /etc/init.d/apache2 reload
 
169
 
 
170
 
 
171
Configuring hostname resolution
 
172
--------------------------------
 
173
 
 
174
All of IVLE's hostnames need to be resolvable from the local system. For a
 
175
production environment, this would be done in DNS. For a development system,
 
176
this is usually done in ``/etc/hosts``. Add this line to that file: ::
 
177
 
 
178
   127.0.1.1 ivle.localhost public.ivle.localhost svn.ivle.localhost
 
179
 
 
180
Code running inside the jail environment also needs to be able to resolve
 
181
those names. Add, to ``/var/lib/ivle/jails/__base_build__/etc/hosts``: ::
 
182
 
 
183
   127.0.1.1 svn.ivle.localhost
 
184
 
 
185
Then refresh the active copy of the jail: ::
 
186
 
 
187
   sudo ivle-buildjail
 
188
 
 
189
 
 
190
Configuring the user management server
 
191
--------------------------------------
 
192
 
 
193
You need to have the IVLE user management server (``usrmgt-server``) running
 
194
for many parts of IVLE to operate properly, so it should be configured to
 
195
start on boot. There is an example init script in
 
196
``examples/config/usrmgt-server.init``. For Debian or Ubuntu, copy it to
 
197
``/etc/init.d/ivle-usrmgt-server``. Start it now, and set it to start
 
198
automatically: ::
 
199
 
 
200
   sudo /etc/init.d/ivle-usrmgt-server start
 
201
   sudo update-rc.d ivle-usrmgt-server defaults 99
 
202
 
 
203
 
 
204
Creating the initial user
 
205
-------------------------
 
206
 
 
207
The final step in getting a usable IVLE set up is creating a user. You'll
 
208
probably want admin privileges - if not, drop the ``--admin``. ::
 
209
 
 
210
   sudo ivle-adduser --admin -p password username 'Full Name'
 
211
 
 
212
You should then be able to browse to ``http://ivle.localhost/``, and
 
213
log in with that username and password.
 
214
 
 
215
.. note::
 
216
   For more advanced configuration, see :ref:`Configuring IVLE
 
217
   <ref-configuring-ivle>`.