← 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: mattgiuca
  • Date: 2008-02-19 00:54:28 UTC
  • Revision ID: svn-v3-trunk0:2b9c9e99-6f39-0410-b283-7f802c844ae2:trunk:500
db: get_user and get_users now return User objects instead of dictionaries.
    This is the major part of replacing dicts with User objects, as it
    propagates upwards.

Propagated User objects up through the following modules:
    listusers.py, dispatch.login, authenticate, userservice, forumutil
All of these now treat users as an object rather than a dict.

To save on the size of the changes so far, login still individually copies
fields over to the session (so the session does not yet store a user object;
that is the second part of this refactor).

WOO!! Revision 500 :)

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