Installer warnings

From Qubit Toolkit

Installation > Installer Warnings

This page lists the technical requirements for installing Qubit/ICA-AtoM.

If the installer discovers an incompatible technical requirement on your system, it will provide a warning and a link to the specific section on this page which provides more information.

[edit] PHP version

[edit] Minimum PHP version

[edit] Required for installation: YES

Qubit requires PHP 5.2.1 or greater.

[edit] Solutions

[edit] On a hosted web server

Ask your hosting provider if they have hosting plans that include PHP 5.2.1 or greater. If your hosting provider does not have a server with a recent version of PHP, there are many reasonably priced providers that do offer this service. See the hosting page for examples.

[edit] On a personal web server or VPS

The steps for upgrading your version of PHP vary greatly depending on your server environment, OS, etc. A simple Google search for instructions on upgrading PHP for your particular environment should turn up step-by-step instructions. A quick search found these basic instructions for upgrading or installing PHP on the Red Hat, CentOS, Ubuntu, FreeBSD, and Debian flavors of Linux.

[edit] Required and recommended PHP extensions

[edit] mbstring extension

[edit] Required for installation: YES

Qubit requires the mbstring library for PHP to support multi-byte language scripts such as Chinese, Japanese, and Arabic.

[edit] Solutions

[edit] On a hosted web server

Many versions of PHP are installed with multi-byte support due to the demand for internationalized web applications. If your hosting provider does not include multi-byte support in their PHP installation, ask if they can provide a version of PHP compiled with the --enable-mbstring directive.

[edit] On a personal web server or VPS

Follow these instructions on how to compile PHP with mbstring support; only the --enable-mbstring directive is required for Qubit.

[edit] xsl extension

[edit] Required for installation: No

Qubit uses the PHP XSL extension for some XML export functions. We recommend installing XSL to enable this functionality and allow migrating data to and from Qubit.

[edit] Solutions

[edit] On a shared web server

Ask you hosting provider if they will install the XLST library and build php with the --with-xsl[=DIR] directive.

[edit] On a personal web server or VPS

Follow these instructions for installing and configuring the XSL extension.

[edit] Imagemagick library

Qubit currently supports thumbnailing for uploaded images, using the "ImageMagick" library (Installing Imagemagick in Ubuntu) or the GD library. ImageMagick also supports generating thumbnails from PDF files - this functionality will be utilized automatically if the ImageMagick library is avaliable.

[edit] FFmpeg library

Qubit requires the ffmpeg library for uploading and viewing video files. This library allows converting a wide range of video and audio formats to the flash video format required for in-browser viewing in Qubit.

[edit] File and directory permissions

[edit] Writable paths

[edit] Required for installation: YES

Qubit requires write access to the "data/", "log/" and "cache/" directories.

[edit] Sample error message

[edit] Solution

In a Linux server environment, you can use the following command to give write access to the required directory to all users:

$ chmod -R 0777 /full/path/to/dirname

[edit] databases.yml not writable

[edit] propel.ini not writable

[edit] .htaccess not writable

[edit] settings.yml not writable

[edit] Required for installation: YES

The Qubit installer requires write access to all four of the above files to properly configure Qubit. The first time the installer is run, it will attempt to create these files, if they don't already exist.

[edit] Solutions

The following solution uses config/databases.yml as an example, but can be used for any of the writable files. The file names with their path from the Qubit root are:

• config/databases.yml
• config/propel.ini
• web/.htaccess (NOTE: this is a "hidden" file in Linux, due to the period at the beginning of it's name. You will not see it with a normal 'ls' command.)
• apps/qubit/config/setttings.yml

[edit] Setting permissions for the databases.yml file

To allow all users to write to the config/databases.yml file on a Linux server, use the command (from the Qubit root directory):

$ chmod 0777 config/databases.yml

[edit] Configuration options

[edit] .htaccess files are completely ignored

[edit] Required for installation: No

Qubit uses a wikipedia:Htaccess .htaccess file to define a number of Apache rules that are used to interpret human-readable web addresses such as "qubit/web/informationobject/edit/id/252". This has a number of advantages, including easier bookmarking of pages, search-engine (such as Google) searchability, and a more intuitive interface for users.

Some Apache servers are configured to ignore .htaccess files to prevent users from creating security holes, or making their website inaccessible.

[edit] Solutions

[edit] Hosted server

Talk to your hosting provider to see if there are special steps that must be taken to enable .htaccess configuration files on your server. Your hosting provider may have a special plan or server for websites that require .htaccess configuration options, or may need to set up .htaccess files for you, in order to ensure that the directives in the file are not harmful.

[edit] Personal web server

See this Apache Tutorial for help with setting up .htaccess in Apache 2.2 (the latest version as of this writing). The Apache site also has documentation for earlier versions of Apache.

The most probable cause of this warning is described in AllowOverride Directive section of the Apache documentation. The relevant line is:

When this directive is set to None, then .htaccess files are completely ignored. In this case, the server will not even attempt to read .htaccess files in the filesystem.

[edit] Options not allowed in .htaccess files

[edit] Required for installation: No

See the .htaccess files are completely ignored section for a short explanation of the .htaccess file and why it is used in Qubit.

Apache allows very fine grained controls of what rules can be defined in the .htaccess file, and some Apache configurations will not allow setting the Options directive in .htaccess.

[edit] Solutions

[edit] Hosted server

Talk to your hosting provider to see if they will configure Apache to allow .htaccess to override the Options directive.

[edit] Personal web server

This warning is most likely due to the AllowOverride Directive. The simplest solution is setting

AllowOverride All

which allows .htaccess to override most Apache configuration options. If completely opening up the override directive is undesirable, then setting

AllowOverride Options Fileinfo

should be sufficient (See the mod_rewrite not enabled section for an explanation of why the Fileinfo directive is necessary).

[edit] mod_rewrite not configured

[edit] Required for installation: No

mod_rewrite is the Apache extension that does the actual work of converting a URL like http://qubit-toolkit.org/qubit/web/informationobject/edit/id/252 into a set of instructions that PHP can understand. The .htaccess files are completely ignored section above has a brief explanation of why this behavior is required for Qubit.

Your Apache web server must have mod_rewrite enabled and allow re-writing rules in the .htaccess file for mod_rewrite to work properly.

This is a good beginner's guide to mod_rewrite, including some good reasons for using mod_rewrite.

[edit] Solutions

[edit] Hosted server

Ask your web provider to enable mod_rewrite and .htaccess mod_rewrite rules for your server.

[edit] Shared web server

As detailed in the Installer Warnings#Options not allowed in .htaccess files section above, your Apache config must, at a minimum, allow .htaccess to override Options and Fileinfo directives. The necessary configuration directive in your Apache configuration file is:

AllowOverride Options Fileinfo

In addition, Apache may not have the mod_rewrite extension enabled by default. To enable mod_rewrite, uncomment the following lines (remove the "#" character at the beginning of the line):

#LoadModule rewrite_module modules/mod_rewrite.so
#AddModule mod_rewrite.c

And restart your Apache server.

[edit] PHP memory limit

[edit] Required for installation: YES

PHP limits the maximum amount of memory that any script may use, to prevent scripts from consuming too much of the system resources. Qubit currently requires a minimum memory limit of 64MB to install properly.

[edit] Solutions

[edit] Hosted server

Ask your hosting provider about how you can increase the "memory_limit" php.ini setting to a value of 64M.

[edit] Personal web server

See Allowed memory size exceeded section for instructions on changing the "memory_limit" in your php.ini file.

[edit] Other issues

[edit] Search index

[edit] Required for installation: YES

Qubit uses the symfony sfLucenePlugin search engine to allow full-text searching of all data stored in the Qubit database.

This warning indicates that there has been a problem when Qubit attempted to build it's search index. The warning message will provide more details about what caused the error.

[edit] Solutions

Please file an issue in the Tools#Bugs_and_issues issues list with a description of the exact error message you received. Your feedback will help developers to fix the problem.

[edit] Allowed memory size exceeded

[edit] Required for installation: YES

By default, PHP is usually installed with a memory limit of 16MB that any PHP script may consume. Currently the Qubit installer requires at least 64MB to install, though we are working to get this below 32MB.

[edit] Sample error message

Fatal error: Allowed memory size of 33554432 bytes exhausted (tried to allocate 8192 bytes) in /home/david/public_html/qubit_test/plugins/sfLucenePlugin/lib/vendor/Zend/Search/Lucene/Storage/File/Filesystem.php on line 160

[edit] Solutions

[edit] On a hosted server, no root access

Ask your hosting provider to increase PHP's allowed memory size to 64MB or more.

Local php.ini file

Some web hosts allow placing a php.ini file in your local web directory to override the default site settings. For Qubit, a php.ini file should be placed in the web/ folder, containing the following line:

memory_limit = 64M;

Further details about using a local php.ini file can be found in this discussion: http://groups.google.com/group/qubit-dev/browse_thread/thread/93c7c5ca083d053c

[edit] On a personal web server, a VPS, or a shared server with root access

1. Locate the php.ini file used by your web server:
   • On a linux system you can try the commands:

     $ locate php.ini
     

     or

     $ find / -name php.ini
     

   • You may find several php.ini files, you want to edit the file in the cgi or apache directory (depending on whether PHP is running as a CGI or mod_php).
   • You can also use phpinfo() in a file to display a list of php.ini settings, including the current location of your php.ini file.
2. Open your php.ini file with your favorite text editor
   • Make sure to open the file with su privileges (use sudo if avaiable)
3. Edit the line below and set the memory limit to 64M:

   memory_limit = 64M      ; Maximum amount of memory a script may consume (16MB)
   

4. Save your changes to php.ini
5. Restart your Apache process (only necessary if PHP is running as an Apache module):

   $ apache2ctl restart
   

[edit] Resource limits section in a typical php.ini file

;;;;;;;;;;;;;;;;;;;
; Resource Limits ;
;;;;;;;;;;;;;;;;;;;

max_execution_time = 30     ; Maximum execution time of each script, in seconds
max_input_time = 60 ; Maximum amount of time each script may spend parsing request data
;max_input_nesting_level = 64 ; Maximum input variable nesting level
memory_limit = 32M      ; Maximum amount of memory a script may consume (16MB)

[edit] Create database

[edit] Required for installation: YES

Qubit requires a DBMS (Database Management System) to store system and archival data. The recommended DBMS for Qubit is MySQL, which is a very popular, open-source solution.

[edit] Solutions

See Installation - Creating your MySQL Database for instructions on setting up a MySQL database for Qubit.