Mica Installation Guide

Mica, is the standard installation profile for having a Mica instance without any content, but all the features enabled.
Mica demo, is an installation profile that will help to illustrate Mica functionalities. This may serve as a good starting point for customizing your web portal.

Post-installation step is required to configure the Mica site according to your specific needs.

Software Requirements

Server Software Requirements

Web server

Apache 1.3, Apache 2.x, or Microsoft IIS

Database server

MySQL 5.0.15 or higher with PDO, SQLite 3.3.7 or higher
Microsoft SQL Server and Oracle are supported by an additional module

PHP

5.3 or higher.

We recommend to configure PHP (edit /etc/php5/apache2/php.ini) with the followings:

memory_limit = 512M
max_execution_time = 60

For more information about Drupal system requirements see http://drupal.org/requirements

Client Software Requirements

To use Mica you must have a recent web browser such as Firefox 3.6, Chrome 8.0 or Internet Explorer 8-9.

Installing Mica

Installation of Mica Debian package (recommended)

OBiBa Debian repository is available at http://pkg.obiba.org. To proceed installation, do as follows:

Install Debian package. Follow the instructions in the repository main page for installing Mica (replace opal by mica).
Install Default Site. Connect to http://localhost/mica to install default site:
- database name is mica,
- database user name is mica,
- database user password is the one provided at the package installation.
Post-install Configuration. See details in Post-install configuration.

Installation of Mica tarball

Download Mica tarball/zip file from http://download.obiba.org/mica/stable. Extract mica from it and follow the instructions in the INSTALL.txt file.
Install site(s). Follow the usual Drupal procedure for installing sites.
Post-install Configuration. See details in Post-install configuration.

Post-install configuration

Enable clean URLs

To allow Drupal to write 'clean urls' (i.e. urls without a the string ?q=), Apache server needs one of its modules to be enabled:

This Apache server configuration is done automatically when installing Mica using the Debian package.

The .htaccess file in mica installation folder is to be modified according to your Mica site base URL (see RewriteBase directive). Then go to Configuration > Clean URLs and enable the feature.

For advanced configuration and more information see Drupal documentation about clean urls.

Sites File Permissions

After a site installation, the corresponding directory permissions must be set for security reasons:

the directory sites/default must not be writable,
the file sites/default/settings.php must not be writable.

For more information see Drupal server permissions recommendations.

File system Configuration

Go to Configuration > File system and modify the public and private files directories according to your needs.

Create Encryption Key Pair

To be able to establish a secured connection with some Opal servers, Mica must provide to them a certificate. To create it, go to Configuration > Mica and configure the key pair. The certificate is then created and can be published to third-party tools to encrypt/decrypt participant data.

Enable File Browser

To enable the IMCE file browser (to be able to upload or browser files on the server), go to ?Configuration > Content Authoring > CKEditor and edit the profiles for which a file browser is needed and set the value of File Browser Settings > File browser type to "IMCE".

You can set IMCE configuration by going to Configuration > Media > IMCE.

Enable Search

Installing Solr

In order for Mica modules/profiles to work, you will first need to set up a Solr server.

Installation of Mica Solr Debian package (recommended)

OBiBa Debian repository is available at http://pkg.obiba.org. Mica Solr Debian package is a Solr server preconfigured for indexing Mica content.

The Mica Solr Debian package is installed automatically when installing Mica Debian package using apt tool. If this was not the case, to proceed Mica Solr installation, do as follows:

The package also provides a daemon script for running Solr server automatically.

Installation of Solr tarball

Download the latest stable version of Solr (1.4.1 at the time of this writing) from Solr download and unpack the archive somewhere outside of your web server's document tree.

For small websites, using the example application, located in $SOLR/example/, usually suffices. In any case, you can use it for developing andd testing. The following instructions will assume you are using the example application, otherwise you should be able to substitute the corresponding paths.

Before starting Solr create backups of the schema.xml and solrconfig.xml files that come with Solr (located in Solr's configuration directory, $SOLR/example/solr/conf/) and copy the two equally named files that are provided with search_api_solr module to Solr's configuration directory. You can then start Solr. For the example application, go to $SOLR/example/ and issue the following command (assuming Java is correctly installed):

Afterwards, go to http://localhost:8983/solr/admin/ in your web browser to ensure Solr is running correctly.

For more details see Search API Solr module.

Enable Search API Server and Indeces

Once Solr server is installed, enable the Search API server and indeces from http://localhost/mica/?q=admin/config/search/search_api.

Once Search API is enabled, you can force the indexing of your web site content by going to the Search API index status page, for instance: http://localhost/mica/?q=admin/config/search/search_api/index/studies_index/status.

Increase Maximum Size of Uploaded Files

If files that will be uploaded to Mica are big, you should Increase upload size in your php.ini.

Set Maximum Execution Time

As the Mica installation steps are very aggressive against the database, the maximum execution time of requests is set to the infinite. This is to be modified after installation is done.

To have the default request execution time (30s), comment following line at the end of the settings.php file:

sites/default/settings.php

For more information see PHP Runtime configuration: max_execution_time.

Installation Troubleshooting

Web Server Error Log

Apache web server logs can be followed during Mica installation using this command line on Linux:

If the installation fails, always refer to this error log when reporting to OBiBa issue tracker.

Updating Mica

Make a full backup of all files, directories, and your database before starting, and save it outside your Drupal installation directory. Instructions may be found at http://drupal.org/upgrade/backing-up-the-db

It is wise to try an update or upgrade on a test copy of your site before applying it to your live site. Even minor updates can cause your site's behavior to change.

Manually update from Mica tarball

Log in as a user with the permission "Administer software updates".

Go to Administration > Configuration > Development > Maintenance mode. Enable the "Put site into maintenance mode" checkbox and save the configuration.

Remove all old core files and directories, except for the 'sites' directory, the original Mica install profile in the 'profiles' directory and any custom files you added elsewhere.
If you made modifications to files like .htaccess or robots.txt, you will need to re-apply them from your backup, after the new files are in place.
Sometimes an update includes changes to settings.php (this will be noted in the release announcement). If that's the case, replace your old settings.php with the new one, and copy the site-specific entries (especially the lines giving the database name, user, and password) from the old settings.php to the new settings.php.

Download the latest Mica release from http://download.obiba.org/mica/stable and extract the archive to your Drupal directory.

Re-apply any modifications to files such as .htaccess or robots.txt.

Run update.php by visiting http://www.example.com/update.php (replace www.example.com with your domain name). This will update the database tables.
If you are unable to access update.php do the following:
- Open settings.php with a text editor.
- Find the line that says:
- Change it into:
- Once the upgrade is done, $update_free_access must be reverted to FALSE.

Go to Administration > Reports > Status report. Verify that everything is working as expected.

Ensure that $update_free_access is FALSE in settings.php.

Go to Administration > Configuration > Development and clear all caches.

Go to Administration > Configuration > Development > Maintenance mode. Disable the "Put site into maintenance mode" checkbox and save the configuration.

Post-update configuration

Update to Mica 1.1

Facet configurations were lost due to Search API and Facet API module major upgrade. To fix this:

Go to Administration > Configuration > Search API.
For each index, click on Edit > Facets and configure your facets.
Go to Administration > Structure > Blocks and configure facet blocks visibility.