BASE 2.0RC2 installation instructions

First time installation instructions for the RC2 release of BASE 2.0 with comments on how to install from a pristine subversion copy.
Information on how to upgrade an existing BASE 2.0 installation.
Information on how to perform migration of a BASE 1.2 installation to BASE 2.0.

Please communicate comments and suggestions regarding these instructions through the BASE 2 feedback channels.

Created by: Nicklas, Jari
Last updated: $Date: 2006-10-02 09:40:47 +0000 (Mon, 02 Oct 2006) $
Copyright © 2005-2006 The respective authors. All rights reserved.

Please understand that this is not a fully tested version of BASE 2. Please browse the BASE 2 web site as well as the mailing lists for more info.

First time BASE 2 server installation

SQL database
Hibernate does support a plethora of database engines, but so far we only work with MySQL and PostgreSQL:

a) MySQL
Download and install MySQL (tested with version 5.0), available from http://www.mysql.com/. You need to be able to connect to the server over TCP, so the skip-networking option must not be used. The InnoDB table engine is also needed, so don't disable them (not that you would). BASE comes pre-configured for MySQL so there is no need to change database settings in the BASE config files.

b) PostgreSQL
PostgreSQL 8.0 seems to be working very well. Actaully sometimes even better than with MySQL. If you want to use Postgres instead of MySQL you will have to edit your base.config file. Uncomment the settings for Postgres and comment out the settings for MySQL.
Java
Download and install Java SDK 1.5, available from http://java.sun.com/. Make sure that you download the JDK version (not the JRE version).
BASE (download and unpacking)
Download BASE 2 and unpack the downloaded file, i.e. tar zxpf base-...tar.gz. If you prefer to have the bleeding edge version of BASE 2.0, perform a checkout of the source from the subversion repository (subversion checkout instructions at BASE 2.0 trac site).

If you choose to download the binary package, skip to the next item. The rest of us, read on and compile BASE 2. If you downloaded a source distribution, unpack the downloaded file tar zxpf base-...src.tar.gz, or you may have performed a subversion checkout. Change to the 'root' base2 directory, and issue ant package. This will create a binary package in the base2 root directory. Unpack this new package (outside of the source file hierarchy), and from now on the instructions are the same however you got the binary.
BASE (SQL database)
Instructions for MySQL and PostgreSQL are available below. The database names, the user, and the password can be changed during the creation of the databases. It is recommended to change the password, the other changes can be made if required.

The database names, the user, and the password are needed in a later step below when configuring BASE.

a) MySQL
Create a new database for BASE, and add a user with at least SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX and ALTER permission for the new database. To do this, connect to your mysql server and issue the next lines:
```
  CREATE DATABASE base2;
  CREATE DATABASE base2dynamic;
  GRANT ALL ON base2.* TO base2user@localhost IDENTIFIED BY 'password';
  GRANT ALL ON base2dynamic.* TO base2user@localhost;
```
The base-2.0RC2/misc/sql/createdb.mysql.sql file contains the above statments and can be used by the mysql command-line tool (remember to edit the user, password, and the database names in the script file before executing the commmand):
```
mysql -uroot -p < ./misc/sql/createdb.mysql.sql
```
The header in the script file contains further information about the script.

b) PostgreSQL
Create a new database for BASE, and add a user with the proper privileges. To do this, login as your PostgreSQL user and issue the next lines:
```
  createuser base2user -P
    # this will prompt for an password for the new user, and issue two
    # more question that should be answered with character 'n' for no.
  createdb --owner base2user --encoding UNICODE base2
  psql base2
    # this will start the psql command line tool. Issue the next line
    # within the tool and quit with a '\q'.
  CREATE SCHEMA "dynamic" AUTHORIZATION "base2user";
```
The base-2.0RC2/misc/sql/createdb.postgresql.sql file contains the above statments and can be used by the psql command-line tool:
```
psql -f ./misc/sql/createdb.posgres.sql template1
```
The header in the script file contains further information about the script.
BASE (file storage setup)
An area for file storage must be setup. Create an empty directory in a proper location in your filesystem, and set the owner to be the same as the one that tomcat server is running as. Remember this location for later use.
BASE (configuration)
Configure BASE, in base-2.0RC2/www/WEB-INF/classes/base.config:
1. Uncomment the database engine section that match your setup.
2. Modify the db.url, db.dynamic.catalog, db.username, and db.password settings to match your choice in step iv) above.
3. Modify the userfiles setting to match your choice in step v) above.
BASE (database initialization)
Change directory to base-2.0RC2/bin and run initdb.sh as
```
    ./initdb.sh password
```
Note, the password you use here is given to the BASE 2 web application user root. If the initialisation script fail, it is most probably a mysql related problem. Make sure mysql accept network connection, and make sure your base2user has the proper credentials (a flush privileges; in mysql might help).
Tomcat
Download and install tomcat 5.5.15 or later, available from http://jakarta.apache.org/tomcat/. We are now recommending everyone to run a late 5.5 release since the trick described in doc/tomcat_with_java_1.5.txt is not needed anymore. [We have previously tested BASE with tomcat releases 5.0.30 and 5.5.7. However, these versions use a built in Java 1.4 compiler, to make it work with Java 1.5 read and follow the instructions in doc/tomcat_with_java_1.5.txt and, consequently, download Apache ANT from http://ant.apache.org/.]

You MUST also make sure that Tomcat uses the SERVER mode of the Java runtime engine (see ticket #99). On Linux you do this by setting the environment variable: CATALINA_OPTS to -server. It is also a good idea to specify the maximum allowed memory to use: -server -Xmx500m sets it to 500 megabytes. Basically add the next line close to the top of the catalina.sh script that comes with tomcat (diectory bin):

    CATALINA_OPTS="-server -Xmx500m"

For more information about Tomcat options see http://www.chemaxon.com/jchem/doc/admin/tomcat.html.

BASE/tomcat
Either move the base-2.0RC2/www directory to the tomcat webapps directory or create a symbolic link from the tomcat webapps directory to the www directory (ln -s /path/to/base2/www base2). Start/restart tomcat, and try http://hostname/base2 (replace base2 with whatever you use in your tomcat webapps directory) in your favourite browser, you should expect to see the BASE login page after a few seconds.

In some cases when redoing the installation, the behaviour of tomcat/apache/base may seem strange. This may be due to tomcat's caching of the applications installed. The easiest way to test whether the caching creates problems is to simply delete the cached files. On SuSE 9.3 this is done by (with tomat5)
```
  rm -rf /etc/tomcat5/base/Catalina/localhost
  rm -rf ~tomcat/work/Catalina
```
BASE, apache and apache/tomcat connector
This step is optional. If you want run the tomcat server through the apache web server, you need to install the apache version 2 web server, available from http://www.apache.org/, and a apache-tomcat connector, available from http://jakarta.apache.org/tomcat/connectors-doc/index.html. So, we got you there;-) To be honest, this item is not really well documented yet since we use SuSE 9.3 on our demo/test server, and apache/tomcat/mod_jk comes preinstalled. What you need to do is:
1. Get that tomcat server running in stand-alone mode.
2. Get the apache 2 server running.
3. Install mod_jk. Note, different version are used for apache 1.3 and 2. In SuSE 9.3 this step is done by installing mod_jk-ap20.
4. Create a workers.properties file in the tomcat base directory (commonly copied from a template).
5. Create a jk.conf file in the apache conf directory (commonly copied from a template), and make sure that jk is added to the modules to be loaded when apache starts.
6. In jk.conf add the lines below and change paths appropriately.
```
  # The following lines makes apache aware of the location of
  # the /base2 context
  Alias /base2 "/srv/www/tomcat5/base/webapps/base2"
  <Directory "/srv/www/tomcat5/base/webapps/base2">
    Options Indexes FollowSymLinks
	  allow from all
  </Directory>
  # The following lines mounts all base2 jsp files to tomcat
  JkMount /base2 ajp13
  JkMount /base2/* ajp13
  # The following lines prohibits users from directly accessing WEB-INF
  <Location "/base2/WEB-INF/">
	  AllowOverride None
	  deny from all
  </Location>
```
You must restart the apache and the tomcat server after above steps.
Done! Setup of BASE is finished. Happy BASEing. Now you can log on to your BASE 2 server as user root (use the password from the database initialization step above).

Upgrade of running BASE 2.0 installation

Upgrading may not be safe on a PostgreSQL database due to a bug in Hibernate. The problem is reported to Hibernate developers.

Shut down the tomcat server, i.e. do something like sudo /etc/init.d/tomcat5.5 stop
Rename your current BASE 2 installation mv base-2.0 base-2.0_old
BASE (download and unpacking)
Download BASE 2 and unpack the downloaded file, i.e. tar zxpf base-...tar.gz. If you prefer to have the bleeding edge version of BASE 2.0, perform a checkout of the source from the subversion repository (subversion checkout instructions at BASE 2.0 trac site).

If you choose to download the binary package, skip to the next item. The rest of us, read on and compile BASE 2. If you downloaded a source distribution, unpack the downloaded file tar zxpf base-...src.tar.gz, or you may have performed a subversion checkout. Change to the 'root' base2 directory, and issue ant package. This will create a binary package in the base2 root directory. Unpack this new package (outside of the source file hierarchy), and from now on the instructions are the same however you got the binary.
You need to transfer settings made from the old installation to the new. This is most easily done by comparing the config file (base-2.0/www/WEB-INF/classes/base.config) between the new and the old install (usually fields db.username, db.password, userfiles).

If you are planning to remake a migration you must delete base2 and base2dynamic databases, and more. You are best of performing a first time installation of BASE in this case.
Note, this is not safe on a PostgreSQL database due to a bug in Hibernate. The problem is reported to Hibernate developers.
It is recommended that you perform an update of your database. Running the update scripts are not always necessary, but the update is safe to perform even in cases when it is not needed. Change directory to /path/to/base-2.0/bin/ and issue:
sh ./updatedb.sh password ; sh ./updateindexes.sh password
where password is the password for the root user account in the BASE application.
As tomcat user, remove cached files and directories. Something like this
```
cd /usr/share/apache-tomcat-5.5.15/
rm -rf work/Catalina
```
Start the tomcat server: sudo /etc/init.d/tomcat5.5 start
Done! Upgrade of BASE is finished.

BASE 1.2 to 2.0 data migration instructions

Disclaimer
We have made extensive testing of the migration from BASE1.2 to BASE2. To our knowledge the migration works but we cannot guarantee perfect functionality. The migration tool is supplied as is and usage is done at your risk. We are commited to solve migration problems at the level of transfering data from BASE 1.2 to 2.0.x, but cannot resolve data loss issues due to imperfect migration in a running BASE 2.0.x server. When you start the migration tool you are required to pass parameter "disclaimer_understood" to the migrate_from_1.2.sh script. Remember to check that the migration performed well before you decide to delete your 1.2 installation.

Verify that your BASE 2.0 installation is up and running before attempting migration. Preferably try to login using the root user through the web interface.

Make sure your BASE 1.2 runs with the latest (pristine) schema version. The migration will only support an unmodified BASE 1.2 installation. If you have an out of date schema version, please upgrade to the latest schema using BASE 1.2 tools before migrating. If you have made local changes to the BASE 1.2 schema you need to patch the BASE 2 schema as well as change the migration program.

There is currently no way to restart a migration. The behaviour of migration is controlled through migration.properties, but you should know what you do when you change parameters in this file.

Migration is performed with the following steps:

To transfer files from BASE 1.2 (default migration behaviour), you must have filesystem access to BASE 1.2 files, i.e. the /path/...base.../data directory containing directories rawdata, uploads, proocols, ...
Change settings in the file base-2.0RC2/dist/www/WEB-INF/classes/migrate.properties. The available options are commented:
1. Modify db1.* parameters to match your BASE 1.2 installation.
2. Set userfiles (note, this is not the same parameter as in base.config) to point to the directory containing the BASE 1 files (defined in a previous step above).
3. Modify root.password.
4. Change the deletefiles setting wisely. If you set deletefiles=yes all BASE 1.2 files will be physically removed when copied to BASE 2. Leave this options as deletefiles=no unless you are absolutely sure of what you are doing.

Run migration utility:

  cd base-2.0RC2/dist/bin
  ./migrate_from_1.2.sh

Migration done! Happy BASEing.