Installation

From Qubit Toolkit

Jump to: navigation, search

Administrator manual > Installation

[edit] 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.

[edit] 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 virtual appliance.

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

[edit] 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.

Also see minimum requirements for more information on the dependencies required for full Qubit functionality.

[edit] Installation platform

[edit] Linux

We use and highly recommend Ubuntu as an easy to use Linux distro with a large and lively community behind it - however, any major Linux distro should be sufficient for running Qubit.

[edit] Mac OS X

Mac OS X 10.5 (Leopard) and later comes with PHP5 and Apache ready to run [1] (Note that MySQL is not installed by default, but it is available [2]) but the default installation does not include the all of the required dependencies by the Qubit engine. You can manually recompile PHP5 with the required dependencies, or install MAMP, which includes Apache, PHP5 and MySQL, and will support the Qubit engine without requiring customization.

[edit] Windows

For Windows users we recommend WAMPServer as a quick, easy way install PHP5, Apache, and MySQL. WAMPServer should run the Qubit engine without further customization required. XAMPP is another good option (which also includes Perl support).

[edit] Download

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

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

Option 1

Checkout Qubit from Subversion repository

Checkout the latest Qubit code from our Google Code repository:

$ svn checkout http://qubit-toolkit.googlecode.com/svn/trunk qubit
  • "qubit" is the target directory for your Qubit installation, you may use any name
  • The checkout may take some time, please be patient

Option 2

Checkout ICA-AtoM or DCB from Subversion repository

Checkout the latest ICA-AtoM or DCB release from the Subversion repository:

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

or

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

The checkout may take some time, depending on the speed of the Google project hosting server on any given day

Option 3

Download ICA-AtoM or DCB tarball
  1. Download the latest tarball release of ICA-AtoM from http://ica-atom.org/download or download the latest tarball release of DCB from http://dcb-gcn.canadiana.org/node/2

  2. Decompress the tarball to the home directory of your web server

    • In an Apache web server environment, the home directory of your web server is typically called "public_html"
    • In a Linux environment, use the following command to decompress the tarball:
    $ tar xz < xx-release-1.x.x.tgz

    - where "xx-release-1.x.x.tgz" is the name of the tarball file you downloaded

[edit] 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.

[edit] 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/" 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.

This page may take some time to load, while it checks that your system meets the requirements to run the 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.

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.

When the system checks are done you will see the link "Continue" under "system checks". Click the link.

[edit] Create a MySQL database

You will now be at the Database configuration page.

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.

Although Qubit was developed and tested with 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.

[edit] Create a MySQL database from the command line

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

- where in the above command, "qubit" is the name of the database - you may create a database with a different name if you prefer.

If access is denied, you may need to add "-u example" to the above command, where example is a MySQL username, e.g. "root". If access is denied and you don't have a MySQL username, ask your hosting provider or system administrator for a MySQL username to create a MySQL database.

Return to your database configuration page enter a database password.

If your MySQL server is not the same as your web server, replace "localhost" with the address of your MySQL server.

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.

Click "Save and continue".

[edit] 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.

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.

[edit] Start using the software!

[edit] Troubleshooting

[edit] 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 "decompress" the .tgz file. That will give you a .tar file which you will then need to "unwrap" to reveal the application directories and files.

[edit] 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.

[edit] My browser returns a "500 Server Error"

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

If you are getting this error and your browser address bar content is like http://255.255.255.255/qubit/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.

[edit] 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.

[edit] I get a blank screen that only reads "System Check"

Your system technical requirement check was interrupted.

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.

[edit] 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.

[edit] I have entered my database information but there is no button to submit it!

This problem occurs when the previous "System check" process doesn't complete properly - this prevents an important system file from being created. To fix the error, simply copy the "apps/qubit/config/settings.yml.tmpl" file to "apps/qubit/config/settings.yml". With Linux the command is:

cp apps/qubit/config/settings.yml.tmpl apps/qubit/config/settings.yml

After copying the file, you will need to clear the application cache, then reload the browser page to proceed.

[edit] 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.

[edit] 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 cause 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.

[edit] 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)
[...]
$

[edit] See also

[edit] Xampp installation

For installing on Windows with XAMPP.

[edit] MAMP installation

For installing on Mac OS X with MAMP.

[edit] Installer warnings

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

[edit] Ubuntu quick start

A make file to quickly build Qubit on Ubuntu 8.04 LTS

Retrieved from "http://qubit-toolkit.org/wiki/index.php?title=Installation"
Personal tools