updated documentation for version 1.5.0

1 files changed, 67 insertions, 53 deletions

diff --git a/boca-1.5.0/doc/INSTALL.txt b/boca-1.5.0/doc/INSTALL.txt
index 6319c82..a107e23 100644
--- a/boca-1.5.0/doc/INSTALL.txt
+++ b/boca-1.5.0/doc/INSTALL.txt
@@ -1,32 +1,35 @@
-(Last modified 13/oct/2011 by cassio@ime.usp.br. See Copyright note below.)
+(Last modified 24/aug/2012 by cassio@ime.usp.br. See Copyright note below.)
 
 Requirements
 ------------
 The system was tested with:
-* postgresql 7.4+ / 8.2+
+* postgresql 8.2+ / 9.1+
 * apache 2.2+
-* php 5.3+ (and some extensions)
+* php 5.3+
+(Please see the specific needs below.)
 
 Installation
 ------------
 
 Before following the steps, you must be sure of:
-* your php are integrated with your web server, 
-* the php extension module for the postgresql (php_pgsql.so or 
-php_pgsql.dll) is installed and configured,
+* your php system is integrated with your web server, 
+* the php extension module for the postgresql (e.g. php_pgsql.so)
+   is installed and configured,
 * the postgresql database management system is running.
 
-Usually that is true if you have installed the following
-ubuntu/debian packages:
-postgresql, postgresql-contrib, postgresql-client, apache2,
-libapache2-mod-php5, php5, php5-cli, php5-cgi, php5-gd,
-php5-mcrypt, php5-pgsql
+Usually that is true if you have installed the following ubuntu/debian 
+packages, as given by an apt-get example line:
+
+apt-get install \
+postgresql postgresql-contrib postgresql-client apache2 \
+libapache2-mod-php5 php5 php5-cli php5-cgi php5-gd \
+php5-mcrypt php5-pgsql
 
 It may be needed to configure some parameters in php.ini, 
 postgresql.conf and pg_hba.conf files. The following lines
 show some important attributes for BOCA:
 
-********* apache boca config file (to be included in /etc/apache2/conf.d/): **********
+********* apache boca config file (to be created as /etc/apache2/conf.d/boca): **********
 <Directory /var/www/boca>
        AllowOverride Options AuthConfig Limit
        Order Allow,Deny
@@ -34,31 +37,30 @@ show some important attributes for BOCA:
        AddDefaultCharset utf-8
 </Directory>
 <Directory /var/www/boca/private>
-       AllowOverride Options AuthConfig Limit
+       AllowOverride None
        Deny from all
 </Directory>
 <Directory /var/www/boca/doc>
-       AllowOverride Options AuthConfig Limit
+       AllowOverride None
        Deny from all
 </Directory>
 <Directory /var/www/boca/tools>
-       AllowOverride Options AuthConfig Limit
+       AllowOverride None
        Deny from all
 </Directory>
 
-
-********* postgresql.conf: *********
-tcpip_socket = true #if using tcp to connect to database (older postgresql's)
-listen_addresses = '*' #newer postgresql's
+********* /etc/postgresql/*/main/postgresql.conf: *********
+tcpip_socket = true #if using tcp to connect to database (older postgresqls)
+listen_addresses = '*' #newer postgresqls
 
 # THE FOLLOWING MAY BE GOOD FOR PERFORMANCE
 max_connections = 100
-maintenance_work_mem = 64MB 
-shared_buffers = 32MB
-work_mem = 3MB
-
+maintenance_work_mem = 32MB 
+shared_buffers = 512MB      ## USE AROUND 1/3 OF YOUR RAM
+work_mem = 10MB
+effective_cache_size = 512MB     ## USE AROUND 1/3 OF YOUR RAM
 
-********* pg_hba.conf: *********
+********* /etc/postgresql/*/main/pg_hba.conf: *********
 #this is the access control file
 #restricting connections from unixsocket or localhost is
 #the best choice, but it could not enough if the
@@ -67,40 +69,39 @@ host    all   all 127.0.0.1 255.255.255.255 md5
 host    all   all 0.0.0.0   0.0.0.0         md5
 # this last line will allow connection from everywhere. If you
 # know the IP address of the machines that will serve as autojudging,
-# then you may restrict the access to only such machine. Anyway,
-# if you have a good password, that should not be a problem.
+# then you may restrict the access to only such machines. Anyway,
+# if you have a good password, that should not be a problem, as we
+# are not expecting this to be available on the internet but only on
+# the local net.
 
-
-
-Steps for installing boca:
+***********
+*********** Steps for installing boca:
 
 1) Unpack the boca file into a internet world readable directory,
+according to the setting you chose in /etc/apache2/conf.d/boca,
 e.g.:
-> mkdir -p /var/www/boca
-> cd /var/www/boca
-> tar xvzf boca-x.y.z.tar.gz
+# cd /var/www
+# tar xvzf boca-x.y.z.tar.gz
+# ln -s boca-x.y.z boca
 
 2) create a postgresql account with permission to create new
 databases (you need database admin privilegies to do that),
 e.g.:
-> psql -h 127.0.0.1 -U postgres -d template1
+# psql -h 127.0.0.1 -U postgres -d template1
 template1=# create user bocauser with password 'boca' createdb;
 template1=# \q
 
 3) edit the file private/conf.php (placed where you unpacked boca), 
-setting up the correct values. Ex:
-  $conf["dblocal"]="true"; // use unix socket to connect?
+in order to set up the correct values for your system. E.g.:
+  $conf["dblocal"]="false"; // use unix socket to connect?
   $conf["dbhost"]="localhost"; // ip address of the db
   $conf["dbname"]="bocadb"; // name of the boca database
-			    // it should be any name
-
   $conf["dbuser"]="bocauser"; // unpriviligied boca user
   $conf["dbpass"]="boca";     // unpriviligied boca password
   $conf["dbsuperuser"]="bocauser"; // priviligied boca user
   $conf["dbsuperpass"]="boca";	   // priviligied boca password
        // note that it is just fine to use the same user for
-       // unpriv and priv access, but you can separate them 
-       // for increasing local security
+       // unpriv and priv access
 
   // secret key to be used in HTTP headers
   // you MUST set it with any random large enough sequence
@@ -108,22 +109,32 @@ setting up the correct values. Ex:
   // CHOOSE ANOTHER NUMBER/STRING AND REPLACE BELOW
   $conf["key"]="secretKey:23894091237589234759234723489";
   
+  // initial password that is used for the user admin -- set it
+  // to something hard to guess if the server is available
+  // online even in the moment you are creating the contest
+  // In this way, the new accounts for system and admin that are
+  // eventually created come already with the password set to this
+  // value. It is your task later to update these passwords to
+  // some other values within the BOCA web interface.
+  $conf["basepass"]="boca";
+
   // the following field is used by the autojudging script
   // set it with IP address (or other short description)
   // of the computer allocated for
   // autojudging during the competition
+  // this is only useful for debug purposes when multiple 
+  // autojudges are being used
   $conf["ip"]='10.10.10.10';
 
-4) run the php script to initialize the boca database
-> cd /var/www/boca/
-> php private/createdb.php
+4) run the php script to initialize the boca database. E.g.
+# cd /var/www/boca/src
+# php private/createdb.php
 
 5) It's all done. Now you have to manage the contest with a 
 browser and boca. Proceed to the ADMIN.TXT file.
 
-
-----------
-==> DETAIL ABOUT MOVING FROM POSTGRES 8.x TO 9.1
+========
+==> DETAIL ABOUT MIGRATING FROM POSTGRES 8.x TO 9.1
 LARGE OBJECTS GET WRONG OWNERSHIP. TO FIX, RUN WITHIN psql:
 # su - postgres
 # psql -d bocadb
@@ -136,23 +147,26 @@ execute 'ALTER LARGE OBJECT ' || r.loid || ' OWNER TO bocauser';
 end loop;
 end$$;
 \q
+========
 
-
-Security Issues
----------------
+========
+Security Issue when BOCA server is not exclusively dedicated to BOCA
+--------------------------
 It is strongly recommended that BOCA be installed on a computer
 with no other users. If the computer where you are installing BOCA
 is used by others (with command line shells), it is essential
-that you change the permission of the file private/conf.php to be
+that you change the permission of the file src/private/conf.php to be
 readable just by the user which the apache server runs and set 
 safe_mode=On in the php.ini file (furthermore, the database access
 must be strictly restricted by passwords). Do it before configuring the 
-private/conf.php file, so no one will be able to see your passwords.
-Moreover, the private/conf.php file must be in a directory owned by the
+src/private/conf.php file, so no one will be able to see your passwords.
+Moreover, the src/private/conf.php file must be in a directory owned by the
 bocauser or www-data or apache (all this combination implies that the only 
-way to read the private/conf.php is from a php script owned by bocauser in 
-the same directory). 
+way to read the src/private/conf.php is from a php script owned by
+bocauser in the same directory). 
+========
 
+========
 Contacts and Copyrights
 -----------------------
 BOCA Copyright (c) 2003- Cassio Polpo de Campos (cassio@ime.usp.br)