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] Getting started

Qubit is a web-based application that runs on a designated server computer. Users access the server from their own computers over a network using standard we browser software. Supported web browsers are: Safari 4.0->, Firefox 3.5->, and Google Chrome (MAC OSX); Firefox 3.5->, Google Chrome, and Internet Explorer 9-> (Windows); and Firefox 3.5-> (Linux/Unix).

[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 programming language. Webserver: We recommend the Apache HTTPD version 2.0 or 2.2 webserver. MySQL Database: We recommend the MySQL version 5.0, 5.1 or 5.5 database. PHP programming language: We recommend PHP version 5.3 or better.

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

The fastest way to get AtoM running on Mac OS X is usually installing the MAMP webserver, which includes Apache, PHP5 and MySQL in one easy to install bundle. However some users have reported issues with installing AtoM in a MAMP environment. Please see the note about digital objects below, as MAMP does not include the optional libraries needed for creating digital derivatives.

If MAMP does not work for you, or you would prefer to install Apache, PHP and MySQL manually, Mac OS X 10.5 (Leopard) and later come with PHP5 and Apache pre-installed. However the default PHP5 installation may not be compiled with the mbstring library, which is required by AtoM. If mbstring support is not included by default in your version of Mac OS X, you will need to manually recompile PHP5 with the required dependencies, or install MAMP (above). MySQL is not installed by default on Mac OS X [1].

If you plan to upload digital objects, please note that some of the optional libraries used by AtoM to create digital derivatives (e.g. ffmpeg, Imagemagick) can be difficult to install in Mac OS X because there are no official "installers". The libraries can be manually compiled (very complex) or installed with a package manager such as MacPorts or Homebrew (moderately complex).

[edit] Windows

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

A screencast on how to install ICA-AtoM 1.2.0 with WAMP is available thanks to @head2head83 (see blog post).

Some people also installed ICA-AtoM successfully using IIS7.

Windows users may also find it difficult to install the optional libraries used by AtoM to create digital object derivatives (e.g. ffmpeg, Imagemagick). Be sure to research the availability of these libraries in Windows if you plan to upload digital objects.

[edit] Download

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

Option 1

Checkout Qubit from Git repository

Checkout the latest Qubit code from our Git repository:

$ git clone git:// 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


$ svn checkout

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 or download the latest tarball release of DCB from
  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] Setting directory and file permissions

Make sure that your web server and PHP have the necessary read and write permissions, follow these instructions.

[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 "" or "" or "". 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; try calling the installer by navigating to [root]/index.php/;sfInstallPlugin (e.g.;sfInstallPlugin)

[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; try calling the installer by navigating to [root]/index.php/;sfInstallPlugin (e.g.;sfInstallPlugin)

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

Your system technical requirement check was interrupted; restart the installer by navigating to [root]/index.php/;sfInstallPlugin (e.g.;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.

[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 '': 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

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
$ 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 support (implies

[edit] MySQL 5.5+ table doesn't exist

500 | Internal Server Error | PropelException
[wrapped: SQLSTATE[42S02]: Base table or view not found: 1146 Table 'qubit_item.information_object_i18n' doesn't exist]

In MYSQL 5.5, Oracle deprecated the "Type=" syntax for "Engine=" syntax, so the SQL to build the database won't work on mysql 5.5.x. To fix the install, you'll have to open data/sql/lib.model.schema.sql and data/sql/plugins.qbAclPlugin.lib.model.schema.sql in an editor, and do a search for "Type=" and replace it with "Engine=".

[edit] See also

[edit] Xampp installation

For installing on Windows with XAMPP.

[edit] WAMP installation

For installing on Windows with WAMP

[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

[edit] Web analytics

An introduction to web analytics and some instructions to deploy Google Analytics.

Personal tools