← 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: chadnickbok
  • Date: 2009-01-13 05:20:59 UTC
  • Revision ID: svn-v3-trunk0:2b9c9e99-6f39-0410-b283-7f802c844ae2:trunk:1107
Fixed an issue with my logout app, and removed a dead reference
to a 'special case' in dispatch

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