Installation

Please note that ICA-AtoM is no longer actively supported by Artefactual Systems.
Visit https://www.accesstomemory.org for information about AtoM, the currently supported version.

Main Page > Administrator manual > Installation

Document in progress. Please refer to https://www.qubit-toolkit.org/wiki/Installation

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.

Getting started

ICA-AtoM 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 8-> (Windows); and Firefox 3.5-> (Linux/Unix).

Minimum requirements

ICA-AtoM 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 ICA-AtoM functionality.

Installation platform

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 ICA-AtoM.

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 ICA-AtoM 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.

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).

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.

Download

Download the latest tarball release of ICA-AtoM from http://ica-atom.org/download.html

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 xvzf < icaatom-1.x.x.tgz

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

Setting directory and file permissions

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

Run the installer

Once you have downloaded ICA-AtoM 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 ICA-AtoM 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/icaatom-1.3.0/". 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.

Create a MySQL database

You will now be at the Database configuration page.

After verifying that your system meets the minimum requirements for running ICA-AtoM, 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 ICA-AtoM 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.

Create a MySQL database from the command line

$ mysql -u username -p -e 'CREATE DATABASE icaatom CHARACTER SET utf8 COLLATE utf8_unicode_ci'

- where in the above command, "icaatom" 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".

Finish 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 ICA-AtoM 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. 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 "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.

Set up directory and file permissions

You will need to set the "owner" of the ICA-AtoM 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 qubit:Installation - Setting directory and file permissions tutorial for instructions.

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. http://255.255.255.255/icaatom/index.php/;sfInstallPlugin)

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. http://255.255.255.255/icaatom/index.php/;sfInstallPlugin)

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. http://255.255.255.255/icaatom/index.php/;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 ICA-AtoM 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,

Fix the problem, or
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 ICA-AtoM, then you can come back and address these warnings later. Click the "Ignore errors and continue" link to continue with installing ICA-AtoM.

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.

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

The ICA-AtoM 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 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.

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

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=".