r2169 - add some comments for future reference
[racktables] / README
diff --git a/README b/README
index 4310be2a907056507569d98594b5c7f2a9e4227f..ca809d402674933632c0a4bd787237f63592b5dd 100644 (file)
--- a/README
+++ b/README
@@ -2,10 +2,10 @@ Thank you for selecting RackTables as your datacenter management
 solution. Feel free to address your questions to the mailing list
 before contacting the authors directly. The project web-site
 (http://racktables.org/) is usually kept up to date with the
-current version and URLs. And we've got a bugtracker finally :)
+current version and URLs.
 
 Mailing list: <racktables-users/=@=/freelists.org>
-Bug tracker and Wiki: http://trac.racktables.org/trac
+Bug tracker and Wiki: http://racktables.org/trac
 Authors: <info/=@=/racktables.org>
 
 *******************************************************
@@ -16,34 +16,58 @@ Authors: <info/=@=/racktables.org>
 
 I. Dependencies.
 
-For database you must have a MySQL server installation version 4.x or 5.x:
-Fedora Core 6: yum install mysql-server mysql
-Fedora 8: yum install mysql-server mysql
-ALTLinux Compact 3.0: apt-get install MySQL-server MySQL-client
-ALTLinux Desktop 4.0: apt-get install MySQL-server 
+For database you must have a MySQL server installation
+version 4.x or 5.x. It is a good idea to make it use UTF-8
+by default.
 
-For web-frontend you must have Apache and PHP 5 with PDO extension:
-Fedora Core 6: # yum install httpd php php-mysql php-pdo php-gd
-Fedora 8: yum install httpd php php-mysql php-pdo php-gd php-snmp
+* Fedora 8/9: yum install mysql-server mysql
+put "default-character-set=utf8" into /etc/my.cnf
 
-II. Layout
+* ALTLinux Desktop 4.0: apt-get install MySQL-server 
+put "CHSET=utf8" into /etc/sysconfig/mysqld
+
+*openSUSE 11.0: YaST -> Software -> software management -> Web and LAMP server -> mysql
+put "default-character-set=utf8" into /etc/my.cnf
+
+For web-frontend you must have Apache and PHP 5 with PDO and multibyte
+extensions:
+
+* Fedora 8/9: yum install httpd php php-mysql php-pdo php-gd php-snmp php-mbstring
+
+* ALTLinux Server 4.0: apt-get install apache2-httpd-prefork php5-gd2 \
+php5-pdo_mysql php5-pdo apache2-mod_php5 php5-mbstring
+
+* openSUSE 11.0: use YaST to apache2-mod_php5, php5-gd, php5-mbstring, php5-mysql,
+php2-snmp and php5-ldap
+
+II. Prepare the server.
 1. Unpack the tarball and make it web-accessible, e.g. http://yourcompany.com/racktables
 or http://racktables.mysite.org.
-2. Edit install/init-auth.sql and change admin password
+2. mysql> create database_name; grant all privileges on database_name.* to XXX@YYY identified by 'ZZZ';
+
 
-III. Database setup
-mysql> create database_name;
+There are two mutually exclusive ways to install RackTables, they are described as III-A and III-B.
+
+
+III-A. HTTP installation (starting with 0.14.12 release)
+Open your RackTables URL and follow the instructions. In a suitable
+environment everything should take a minute or so.
+
+
+III-B. Manual installation.
+1. Edit install/init-auth.sql and change admin password
+
+2. Init database.
 mysql> use database_name;
 mysql> source install/init-structure.sql
 mysql> source install/init-auth.sql
 $ rm -f install/init-auth.sql
 mysql> source install/init-dictbase.sql
 mysql> source install/init-dictvendors.sql
-mysql> grant all privileges on database_name.* to XXX@YYY identified by 'ZZZ';
 
-Make sure your inc/secret.php matches real values you used in the above request.
+3. Edit inc/secret.php
 
-IV. $ rm -f install/init-auth.sql
+4. $ rm -f install/init-auth.sql
 (Just to be sure you did.)
 
 *******************************************************
@@ -62,3 +86,52 @@ procedure should be sufficient:
 3. Open the RackTables page in your browser.
 4. Follow instructions. Normally, everything should be Ok. If it
    is not so, write down the failed quieries for further investigation.
+
+*******************************************************
+*                                                     *
+*                   RELEASE NOTES                     *
+*                                                     *
+*******************************************************
+
+*** Upgrading to 0.14.12 ***
+
+The upgrade may show a failed query "alter database character set utf8", in
+this case the user should issue the query manually from the mysql command
+line.
+
+*** Upgrading to 0.16.0 ***
+
+This release features a completely new authorization system, RackCode,
+which brings the tags feature (introduced in 0.15.0) to its full potential.
+The old-style user permissions are converted during upgrade automatically,
+but the result may appear not what you would expect. Review the RackCode
+after upgrade (Main page -> Configuration -> Permissions) and adjust,
+if necessary.
+
+Another important change is a new dependency on "multibyte string" PHP
+extension. Normally one should get it working before starting the upgrade,
+this is typically achieved by installing a particular PHP RPM from the
+standard package repository (and restarting Apache after that):
+
+Fedora: yum install php-mbstring
+ALTLinux: apt-get install php5-mbstring
+
+*** Upgrading to 0.16.1 ***
+This release fixes a missing UNIQUE key in the database. However, this fix
+may sometimes fail, if the table contains duplicate records. If the
+0.16.0-0.16.1 upgrade batch completed without errors, no action needs to be
+taken. If you see a failed ADD UNIQUE query during upgrade, the only solution
+is to delete the duplicates manually. To do this, open a MySQL console and
+issue the failed query again:
+
+mysql> alter table IPVirtualService ADD UNIQUE endpoint (vip, vport, proto);
+
+The IP address of the duplicate VS will be known from the "Duplicate entry"
+message. For example, to decode "Duplicate entry '180879877-80-TCP' for key
+2" error message, issue:
+
+mysql> select inet_ntoa(180879877);
+
+Then go to "virtual services" web-interface page and adjust the data as
+necessary. You would need to get rid of the duplicates accurately one by
+one, repeating the ADD UNIQUE query until it succeeds.