Installation

From Qubit Toolkit

Administrator manual > Installation

Qubit, ICA-AtoM or DCB?

These installation instructions apply equally to Qubit, ICA-AtoM, and DCB. If you are not sure which one to use, see the Qubit, ICA-AtoM or DCB? page.

Intended audience

While we have tried to make this document usable by readers with a broad range of technical knowledge, it may be too complex if you have no previous experience with installing web applications or using the Linux command line.

If you are a non technical reader and are just interested in trying out ICA-AtoM, please check out the ICA-AtoM online demo or demo CD. If you are a non technical reader and are just interested in trying out DCB, please check out the DCB online demo.

Minimum requirements

Qubit is a database driven, web based application written in PHP. The instructions assume you have a web server and database server installed on your system, as well as PHP 5.2.1 or higher. We recommend the Apache web server and MySQL database. For Windows users we recommend you use XAMPP to install PHP, Apache, and MySQL, see Xampp installation.

See also the minimum requirements for more information.

Download

You can only download Qubit as a checkout from our Subversion repository using a Subversion client.

Both ICA-AtoM and DCB can be downloaded as a tarball (zip file) or as a Subversion checkout.

$ svn checkout http://qubit-toolkit.googlecode.com/svn/trunk qubit-dir

$ svn checkout http://qubit-toolkit.googlecode.com/svn/branches/ica-atom ica-atom-dir

$ svn checkout http://qubit-toolkit.googlecode.com/svn/branches/dcb dcb-dir

$ tar xvz < xx-release-1.x.x.tgz

Set up directory and file permissions

You will need to set the "owner" of the Qubit web application directories and files to your Apache user in order for the web installer to work properly.

If you have experience with setting directory permissions for web applications, you probably already know how to do this. For everybody else, please read our Installation - Setting directory and file permissions tutorial for instructions.

Run the installer

Once you have downloaded Qubit, ICA-AtoM or DCB and set your permissions you are ready to run the installer. The installer provides a simple web interface to guide you through the installation process, mostly all of which is automated for you.

Open Qubit, ICA-AtoM or DCB in your web browser

The actual web address (URL) of the web installer can vary greatly depending on your web server configuration - you only need to point to the root of the Qubit, ICA-AtoM or DCB web application. The URL will usually be something like "http://255.255.255.255/qubit-dir/" or "http://255.255.255.255/icaatom-1.0.8/" or "http://255.255.255.255/dcb-1.0.8/". Please check your hosting provider's website for information about how to access your website from the internet.

NOTE: This page may take some time to load, while it checks that your system meets the requirements to run your Qubit application. You will only see a blank page while it is performing this check. It is working as long as your browser indicates that it is still waiting for a response.

WARNING Do not interrupt the System Check process. If you do, you will have to delete the application directory and unzip the tarball again or perform a fresh repository checkout.

Please see the troubleshooting section below if you see a warning message on the "Check System" page.

Create your MySQL database

After verifying that your system meets the minimum requirements for running Qubit, the installer will ask you for information about where to store your Qubit data. At this point you will need to create a database for Qubit to use.

NOTE: Although Qubit was developed and tested using MySQL, the application is built on the symfony framework and uses the Propel database abstraction layer. This should theoretically allow using other DBMS' for data storage. Propel 1.2 supports MySQL, MS SQL Server, PostgreSQL, SQLite and Oracle. However, we have limited time and resources and can not currently provide support for any databases other than MySQL.

Creating a MySQL database from the command line

• Create a new database for Qubit, with UTF8 support:

$ mysql -u username -p -e 'create database qubit character set utf8 collate utf8_unicode_ci'

• Create a user and password for the Qubit application:

$ mysql -u username -p -e 'grant all on qubit.* to qubit@localhost identified by "ak389k2ck7s"'

NOTE:

• For security reasons, it is best to create a unique user for the qubit application with a random password (it doesn't need to be something you can remember). The password is 'ak389k2ck7s' in the example above, please do not use this as *your* password.
• If your MySQL server is not the same as your web server, replace 'localhost' with the IP of your MySQL server.
• qubit can be any name you want for your qubit database, the username 'qubit' can also be changed to whatever you wish.
• You can of course use any method you want for creating your MySQL database. phpMyAdmin is often installed with PHP hosting packages, and is easy to use.

Finish installation

A successful Qubit Installation!

Follow the prompts to complete the installation.

Last step is to configure your site title and description, as well as creating an admin user.

NOTE: Configuring Qubit and loading the test data will take some time. Please be patient!

If all goes well, you should see the page shown to the right (with an ICA-AtoM or DCB logo if you are using either one of those). If not, refer to the troubleshooting section below.

Start using the software!

Troubleshooting

I can't unzip the tarball file on Windows

The tarball is like an onion with two layers. You may have to unzip the files twice. The first time is to de-compress the .tgz file. That will give you a .tar file which you will need to unwrap to reveal the application directories and files.

My browser returns a '500 Server Error'

The installer may not have been triggered from your root directory.

• If you are using release 1.0.4 or earlier, try calling the installer by navigating to [root]/web/install/index.php (e.g. http://255.255.255.255/qubit-dir/web/install/index.php)
• If you are using release 1.0.5 or later, try calling the installer by navigating to [root]/web/sfInstallPlugin (e.g. http://255.255.255.255/qubit-dir/web/sfInstallPlugin)

If you are getting this error and your browser address bar content is like http://255.255.255.255/qubit-dir/web/install.php/sfInstallPlugin, try to clear your browser's cookies. This is a known issue (issue 1125) in 1.0.8.1 which causes a conflict with old installation cookies. It will be resolved in next release. Please note that while deleting your cookies may resolve the problem, it will also remove your saved settings for sites you've previously visited. Fortunately, last Firefox releases allow users to remove site cookies selectively. Some users already had this problem and one of them resolved it with us through chat room, you can see the log for more help.

My browser says it is 'done' but it is only displaying a blank page

The installer may not have been triggered from your root directory.

• If you are using release 1.0.4 or earlier, try calling the installer by navigating to [root]/web/install/index.php (e.g. http://255.255.255.255/qubit-dir/web/install/index.php)
• If you are using release 1.0.5 or later, try calling the installer by navigating to [root]/web/sfInstallPlugin (e.g. http://255.255.255.255/qubit-dir/web/sfInstallPlugin)

I get a blank screen that only reads 'System Check'

Your system technical requirement check was interrupted.

• If you are using release 1.0.4 or earlier, re-start the installer by navigating to [root]/web/install/index.php (e.g. http://255.255.255.255/qubit-dir/web/install/index.php)
• If you are using release 1.0.5 or later, re-start the installer by navigating to [root]/web/sfInstallPlugin (e.g. http://255.255.255.255/qubit-dir/web/sfInstallPlugin)

A white page should load again and your browser should indicate that it is waiting for a response. Be patient, this can take some time.

I get a red box with warning text on the "Check system" page

This is where you will be notified if your web server is not fully compliant with the minimum requirements of the Qubit web application. A full list of installer warnings addresses each warning message encountered in the web installer, and explains the details of why you are getting a particular warning message. The warning text will also link you to the corresponding section on the installer warnings page which includes instructions to help you make the warning message go away!

You have two choices if you receive a warning on the "Check Status" page,

1. Fix the problem, or
2. Ignore the warning and continue with installation

Option #1 is definitely the ideal, but it may not be possible to install special libraries or applications on your server, depending on your hosting environment. Please click the warning text to see contextual help for fixing any problems for you installation. After fixing the problem, click the "Try again" link to verify that the problem has really been fixed before proceeding.

Option #2 is not recommended and in the case of "Required" dependencies will not even be possible. However, if the failed dependency (or dependencies!) are "Not Required" and you can't wait to get started with Qubit/ICA-AtoM, then you can come back and address these warnings later. Click the "Ignore errors and continue" link to continue with installing Qubit.

I get an error like "Fatal error: Allowed memory size of 33554432 bytes exhausted (tried to allocate 8192 bytes)"

The Qubit web installer currently requires at least 64MB of memory to run (we are working on reducing this). PHP 5 has a default memory cap of 32MB. See allowed memory size exceeded for how to increase the allowed memory for PHP.

I get an error like "Unable to parse file '...data/fixtures/sampleData.yml': Malformed inline YAML string { ..."

The PHP mbstring extension is currently required in order to support strings with multi-byte characters, however if misconfigured, it can YAML parsing errors like this. You should not modify the [mbstring] section of your php.ini file because that appears to be the cause of the YAML parsing error.

Utf8Num analyzer needs PCRE unicode support to be enabled

http://groups.google.com/group/qubit-dev/browse_thread/thread/6ba4de1050472537

This exception is thrown at plugins/sfLucenePlugin/lib/vendor/Zend/Search/Lucene/Analysis/Analyzer/Common/Utf8Num.php:61

        if (@preg_match('/\pL/u', 'a') != 1) {
            // PCRE unicode support is turned off
            require_once 'Zend/Search/Lucene/Exception.php';
            throw new Zend_Search_Lucene_Exception('Utf8Num analyzer needs PCRE unicode support to be enabled.');
        }

As far as I can tell, PCRE unicode support does not depend on any PHP compile time or runtime configuration, but on unicode properties support in the underlying PCRE library. You can run the test from Utf8Num.php against the PCRE library directly using the pcretest command,

$ pcretest
PCRE version 7.8 2008-09-05

  re> /\pL/<bsr_unicode>
data> a
 0: a
data> ^C
$

This assumes that PHP is compiled against the same PCRE library as pcretest.

If you build the PCRE library without the --enable-unicode-properties option, the test fails,

$ wget ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/pcre-7.8.tar.bz2
[...]
$ tar xvj < pcre-7.8.tar.bz2
[...]
$ cd pcre-7.8
$ ./configure
[...]
    Unicode properties .............. : no
[...]
$ make
[...]
$ ./pcretest -C
[...]
  No Unicode properties support
[...]
$ ./pcretest
PCRE version 7.8 2008-09-05

  re> /\pL/<bsr_unicode>
Failed: support for \P, \p, and \X has not been compiled at offset 1
  re> ^C
$

If you rebuild with the --enable-unicode-properties option, the test succeeds,

$ ./configure --enable-unicode-properties
[...]
    Unicode properties .............. : yes
[...]
$ make
[...]
$ ./pcretest -C
[...]
  Unicode properties support
[...]
$ ./pcretest
PCRE version 7.8 2008-09-05

  re> /\pL/<bsr_unicode>
data> a
 0: a
data> ^C
$

The rebuilding with the --enable-utf8 option is not sufficient. It is also not necessary because the --enable-unicode-properties option implies --enable-utf8,

$ ./configure --help
[...]
  --enable-unicode-properties 
                          enable Unicode properties support (implies
                          --enable-utf8)
[...]
$

See also

Xampp installation

For installing on Windows with XAMPP.

MAMP installation

For installing on Mac OS X with MAMP.

Installer warnings

For a list of most warnings you may encounter during the install process.

Ubuntu quick start

A make file to quickly build Qubit on Ubuntu 8.04 LTS