20.2. Installation instructions

Java

Download and install Java SE 7, available from http://www.oracle.com/technetwork/java/javase/downloads/index.html. You can select either the JDK or the JRE version.

[Important] Important

As of BASE 3.3 Java SE 7 is required. BASE will no longer run on Java SE 6 or lower.

Set up an SQL database

BASE utilise Hibernate for object persistence to a relational database. Hibernate supports many database engines, but so far we only work with MySQL and PostgreSQL.

MySQL

Download and install MySQL (tested with version 5.1), 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 do not disable them (not that you would) but you may want to tune the InnoDB behaviour before creating BASE databases. BASE comes pre-configured for MySQL so there is no need to change database settings in the BASE configuration files.

PostgreSQL

PostgreSQL 9.1 seems to be working very well with BASE and Hibernate. Download and install PostgreSQL, available from http://www.postgresql.org/. You must edit your <base-dir>/www/WEB-INF/classes/base.config file. Uncomment the settings for PostgreSQL and comment out the settings for MySQL.

BASE (database engine)

The database names (base2 and base2dynamic are used here), the db_user, and the db_password can be changed during the creation of the databases. It is recommended to change the db_password, the other changes are optional and can be made if desired. The database names, the db_user, and the db_password are needed below when configuring BASE.

[Note] Note
Note that the db_user name and db_password set here is used internally by BASE in communication with the database and is never used to log on to the BASE application.
[Important] The database must use the UTF-8 character set

Otherwise there will be a problem with storing values that uses characters outside the normal Latin1 range, for example unit-related such as µ (micro) and Ω (ohm).

MySQL

Create a new database for BASE, and add a db_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 DEFAULT CHARACTER SET utf8;
CREATE DATABASE base2dynamic DEFAULT CHARACTER SET utf8;
GRANT ALL ON base2.* TO db_user@localhost IDENTIFIED BY 'db_password';
GRANT ALL ON base2dynamic.* TO db_user@localhost;

If you download BASE (instructions below) you find a file <base-dir>/misc/sql/createdb.mysql.sql that contains the above statements and can be used by the mysql command-line tool (remember to edit the db_user, db_password, and the database names in the script file before executing the command): mysql -uroot -p < <base-dir>/misc/sql/createdb.mysql.sql. The header in the script file contains further information about the script.

PostgreSQL

Create a new database for BASE, and add a db_user with the proper privileges. To do this, log in as your PostgreSQL user and issue these lines (omit comments):

createuser db_user -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 db_user --encoding UTF8 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 "db_user";

If you download BASE (instructions below) you find a file <base-dir>/misc/sql/createdb.postgresql.sql that contains the above statements and can be used by the psql command-line tool: psql -f <base-dir>/misc/sql/createdb.posgres.sql template1 The header in the script file contains further information about the script.

BASE (download and unpacking)

Download BASE and unpack the downloaded file, i.e. tar zxpf base-...tar.gz. If you prefer to have the bleeding edge version of BASE, perform a checkout of the source from the subversion repository (subversion checkout instructions at BASE trac site).

If you choose to download the binary package, skip to the next item. The rest of us, read on and compile BASE. 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.bin. 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 irrespective where you got the binary package.

This section is intended for advanced users and programmers only. In cases when you want to change the BASE code and try out personalised features it may be advantageous to run the tweaked BASE server against the development tree. Instructions on how to accomplish this is available in the building BASE document. When you return back after compiling in the subversion tree you can follow the instruction here (with obvious changes to paths).

BASE (file storage setup)

An area for file storage must be setup. Create an empty directory in a proper location in your file system. Set the owner of the created directory to the user the Tomcat server will be running as. Tomcat server set up instructions will follow below. Remember this location for later use. The default location is /usr/local/base2/files.

BASE (plug-in setup)

An area for plug-in and extensions installation must be setup. Create an empty directory in a proper location in your file system, and make sure that the user that the Tomcat server will be running as has read permission in this directory. Tomcat server set up instructions will follow below. Remember this location for later use. The default location is /usr/local/base2/plugins.

BASE (configuration)

Basic BASE configuration is done in <base-dir>/www/WEB-INF/classes/base.config:

  • Uncomment the database engine section that match your setup.
  • Modify the db.url, db.dynamic.catalog, db.username, and db.password settings to match your choice above. (database host and database name (e.g. base2), e.g. base2dynamic, db_user, and db_password, respectively.)
  • Modify the userfiles setting to match your choice in file storage setup above.
  • Modify the plugins.dir setting to match your choice in plug-in setup above.

See the Appendix B, base.config reference for more information about the settings in the base.config file.

Optional but recommended. You may want to modify extended properties to fit your needs. Extended properties are defined in <base-dir>/www/WEB-INF/classes/extended-properties.xml. There is an administrator document discussing extended properties available. If you plan to perform a migration of a BASE version 1.2 database you should probably not remove any extended properties columns (this is not tested so the outcome is currently undefined). However, adding columns does not affect migration.

BASE (database initialisation)

Change directory to <base-dir>/bin and execute the following commands:

sudo ./initdb.sh [base_root_login] base_root_password
./updateindexes.sh

In the first command sudo is required because a file will be created in the directory defined by userfiles above. If the directory is writable by you then sudo is not needed.

The second command is important for PostgreSQL users since the Hibernate database initialisation utility is not able to create all required indexes. BASE will work without the indexes but performance is impaired. Running the script as a MySQL user does not have a negative impact.

[Important] Important

The base_root_login and base_root_password you use here is given to the BASE web application root user account. The base_root_login is optional. If not specified, root is used for the login.

If the initialisation script fails, it is probably a problem related to the underlying database. Make sure that the database accepts network connection and make sure that db_user has proper credentials. You may also get a Permission denied on file extension-settings.xml if you do not have write permission to the directory defined by variable userfiles in file base.config. If the initialisation fails on extension-settings.xml you must drop the database and recreate the database as described in BASE (database engine).

Tomcat

Download and install Apache Tomcat 7.0.30 or any later 7.x release, available from http://tomcat.apache.org.

[Important] Important

As of BASE 3.3 Tomcat 7 is required. BASE will no longer run on Tomcat 6 or lower.

There are a few configuration options that are needed to make Tomcat work properly with BASE. The options are set in the CATALINA_OPTS environment variable.

  • Increase the amount of memory that Tomcat is allowed to use. The default setting is usually not enough. To give Tomcat 1 gigabyte, use -Xmx1G.

  • Disable strict parsing of JSP files. -Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false

  • Unless you have manually downloaded and installed JAI (Java Advanced Imaging) native acceleration libraries (see http://java.sun.com/javase/technologies/desktop/media/jai/) it is a good idea to disable the native acceleration of JAI. -Dcom.sun.media.jai.disableMediaLib=true

  • Enable headless mode if your are setting up a server which doesn't have a display device connected to it. -Djava.awt.headless=true.

Depending on your system there are probably several ways to set the the CATALINA_OPTS variable. One suggestion is to add the following line (as a single line) close to the top of the catalina.sh script that comes with Tomcat (directory bin):

CATALINA_OPTS="-Xmx1G 
-Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false
-Dcom.sun.media.jai.disableMediaLib=true
-Djava.awt.headless=true"

For more information about Tomcat options see http://tomcat.apache.org/tomcat-7.0-doc/index.html.

BASE and Tomcat

Do the following:

  • Either move the <base-dir>/www directory to the Tomcat webapps directory or create a symbolic link from the Tomcat webapps directory to the <base-dir>/www directory

    cd /path/to/tomcat/webapps
    ln -s /path_to_base/www base2

  • Make sure that user Tomcat is running as can read all objects in the directory defined by plugins.dir in file base.config.

  • Make sure that user Tomcat is running as owns (i.e., can read, write, delete and create) all objects in the directory, as well as the directory itself, defined by userfiles in file base.config.

  • If you plan to install extensions you should make sure that the <base-dir>/www/extensions directory is writable by the user account Tomcat is running as.

and finalise with start, or restart, Tomcat, and try http://hostname:8080/base2 (change hostname to your hostname and base2 if you selected another name for the BASE Tomcat application) in your favourite browser. The BASE log-in page should appear after a few seconds.

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://httpd.apache.org/, and a apache-tomcat connector, available from http://tomcat.apache.org/connectors-doc/index.html

Setup done!

Happy BASEing. Now you can log on to your BASE server as user root (use the base_root_password from the database initialisation step above). You should begin with creating a couple user accounts, for more information on how to create user accounts please refer to Chapter 22, Account administration.