← 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: Matt Giuca
  • Date: 2009-12-01 04:27:58 UTC
  • mfrom: (1164.2.46 sphinx-docs)
  • Revision ID: matt.giuca@gmail.com-20091201042758-wuxd9bdec00c283i
Merged sphinx-docs branch. This adds Sphinx documentation for the entire IVLE system (for system administrators and developers), and removes all of our random old document files (all either irrelevant, or moved into the Sphinx docs nicely). Currently incomplete, but ready to merge.

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>`.