ATiM Installation Guide

From CTRNet Wiki
Jump to: navigation, search

Contents

System Requirements

Development/Test Environments

Our development server has the following specifications:

  • Dual 2.8GHz Intel Xeon Processors
  • 1GB RAM
  • 70GB Disk space

This server has provided us with ample processing power and disk space to handle multiple installations of ATiM along with other development resources including a FTP server and Subversion repository.

To setup either a development or a test or a demo installation under Windows, we highly recommend installing WAMP (wee WAMP Configuration Guide).

Production Server

As ATiM has been developed using cross-platform, open source technologies any platform capable of running MySQL, Apache and PHP should be able to host an installation.

To date we have installed and tested ATiM on:

Disk space depends on the number of participants, samples and level of annotation. As a rough guide 1.0 GB of free disk space should provide ample room for any established bank (considering no images or documents has to be stored on the server).

For ATiM version 2.7.x

The OS listed below are tested but normally ATiM can be installed on all new versions of Linux distributions

  • OS server
    • Ubuntu 16 (tested and recommended)
    • Centos 7.5 (tested)
    • Windows server 2003/2008/2012 (2008 and 2012 tested)
    • Windows 7, 10 (tested but not a server OS)
  • Web server
    • Apache2 2.4.x
    • IIS 6.0, 8.0, 10
  • Database
    • MySQL 5.4, 5.5, 5.6, 5.7 (recommended)
    • MariaDB 10.3 (tested)
  • PHP 5.6, 7.0 (7.0 recommended)

PHP

PHP needs to have the following modules.

Modules
Module Reference Compile flag
Multibyte String [1] --enable-mbstring
Zlib [2] --with-zlib
One of mysql or mysqli [3], [4] --with-mysql, --with-mysqli
(To confirm) PHP Data Object [5] --enable-pdo --with-pdo-mysql
(For apache onyl) One of apxs or apxs2 --with-apxs=[DIR], --with-apxs2=[DIR]

Example configuration flags

  --enable-mbstring --with-mysql --with-mysqli --enable-pdo --with-pdo-mysql --with-apxs2=/usr/bin/apxs2 --with-zlib
php.ini

First be sure you correctly defined the path to the loadable extensions (modules),

  ; Directory in which the loadable extensions (modules) reside.
  extension_dir ="C:/path_to_the_bin_php_directory/phpx.x.xx/ext/"
  extension=php_mysql.dll
  extension=php_mysqli.dll
  ;;;;;;;;;;;;;;;;;;;
  ; Resource Limits ;
  ;;;;;;;;;;;;;;;;;;;
  
  max_execution_time = 90     ; 90 seconds should be enough to run the majority of queries
  memory_limit = 384M         ; 128M should be enough to run the majority of queries
  ;;;;;;;;;;;;;;;;;;
  ; Fopen wrappers ;
  ;;;;;;;;;;;;;;;;;;
  
  ; If your scripts have to deal with files from Macintosh systems,
  ; or you are running on a Mac and need to deal with files from
  ; unix or win32 systems, setting this flag will cause PHP to
  ; automatically detect the EOL character in those files so that
  ; fgets() and file() will work regardless of the source of the file.
  auto_detect_line_endings = On
  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  ; Add Following line to file ;
  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  
  max_input_vars=5000;
  session.auto_start = 1

Client

ATiM is a web application designed to be used at a resolution of 1024x768 or higher. Lower resolutions can be used but will result in a diminished user experience. Any client running a recent web browser should be able to connect and use ATiM.

CTRNet has tested and recommends the following web browsers for client workstations:

  • FireFox ∞ (A scrolling issue was found in Firefox 12. Bug Report)
  • Internet Explorer 8 or higher
  • Safari 5
  • Chrome ∞

Quick Install Guide (Step by Step)

Setup

Copy over the entire ATiM application code in the document 'root' of your webserver or in a sub-directory of this one.

Please note that the entire application code can be located everywhere else on you server but some specific changes have to be done (see the alias creation on apache or the rewrite rules creation on either IIS6 or the IIS 8).

Set up the database
mysql -u {username} -p{password} {atim_database} --default-character-set=utf8 < atim_v2.7.0_full_installation.sql
mysql -u {username} -p{password} {atim_database} --default-character-set=utf8 < atim_v2.7.1_full_installation.sql

To activate the user 'administrator' (username='administrator' & password='administrator')

mysql -u {username} -p{password} {atim_database} -e "UPDATE users SET password = '81a717c1def10e2d2406a198661abf8fdb8fd6f5', flag_active = 1 WHERE username = 'administrator'"

To complete the installation with the 'demo' data

mysql -u {username} -p{password} {atim_database} --default-character-set=utf8 < ./DemoData/atim_v2.7.1_demo_data.sql
Database Access Configuration

Open the database.php file in the ' ./app/config/ ' directory and complete following information.

   public $default = array(
       'datasource' => 'Database/Mysql',
       'persistent' => false,
       'host' => '127.0.0.1',
       'login' => '{username}',
       'password' => '{password}',
       'database' => '{atim_database}',
       'prefix' => ,
       'encoding' => 'utf8',
       'port' => 3306
   );
Change Mode Access

Open the core.php file in the ' ./app/config/ ' directory and change the value of the '$debug' variable to switch from debug mode to prod mode. Changing the '$isTest' variable from 0 to 1 will also change the ATiM installation header color to red and add a 'Test' word at the end of the header.

 /**
  * CakePHP Debug Level:
  *
  * Production Mode:
  * 0: No error messages, errors, or warnings shown. Flash messages redirect.
  *
  * Development Mode:
  * 1: Errors and warnings shown, model caches refreshed, flash messages halted.
  * 2: As in 1, but also with full debug messages and SQL output.
  *
  * In production mode, flash messages redirect after a time interval.
  * In development mode, you need to click the flash message to continue.
  */
 $debug = 2;
 Configure::write('debug', $debug);
 
 /**
  * ATiM Prod vs Test.
  *
  * 1: Core install name color will be changed to red and 'Test' word will be added to the install name.
  * 0: Install name will be displayed as usual.
  */
 
 $isTest = 1;
 Configure::write('IsTest', $isTest);
Set Up Password Business Rules

Many core variables will help you to apply your institution policies regarding users passwords management. See Login and Password Rules Configuration.

Set Up ATiM Folders Permissions

Change security properties of following folders ' ./app/tmp ' and ' ./app/Locale ' (see either Apache, IIS6 orIIS 8 documentation).

For ATiM versions >= v2.7.1, same permissions should be applied on folders used to :

 /**
  * Record any ATiM user log into a txt file 'user_logs.txt' recorded in a directory of the server.
  * The 'user_logs.txt' will gather
  * information about the visited page, the date and the id of the user.
  *
  * Keep variable to null if no user log file has to be created or replace null by the path of the directory
  * where the log file has to be created.
  */
 Configure::write('atim_user_log_output_path', '/ATiM/...);
Other Core Variables
  • Order
 /**
  * Set the allowed links that exists between an OrderItem and different Order plugin objects:
  * 1 => link OrderItem to both Order and OrderLine (order line submodule available)
  * 2 => link OrderItem to OrderLine only (order line submodule available)
  * 3 => link OrderItem to Order only (order line submodule not available)
  */
 Configure::write('order_item_to_order_objetcs_link_setting', 1); // SampleMasters.batchDerivative()
 
 /**
  * Set the type(s) of item that could be added to order:
  * 1 => both tma slide and aliquot
  * 2 => aliquot only
  * 3 => tma slide only
  */
 Configure::write('order_item_type_config', 1);
Launch Application

According to the ATiM source code directory, the application can be launched from your web browser with following url:

http://localhost

Setup Troubleshooting

This section contains a list of some troubleshooting for ATiM.

Problem Possible cause Solution
Date(): It is not safe to rely on the system's timezone settings. The default timezone used by the date functions has probably not be defined in your php.ini Open your php.ini file. Add following lines and restart your server.
[Date]
; Defines the default timezone used by the date functions
; http://php.net/date.timezone
date.timezone ="UTC"
'PHP "max_input_vars" is <= than atim databrowser_and_report_results_display_limit' Non-consistent definition of php variables and ATiM variables that will generate an error when using the databrowser. Open the php.ini file and change max_input_vars value to a biggest value then restart the server

OR

Open the core.php of the ATiM source code and change core variable databrowser_and_report_results_display_limit to a lowest value.

'warning_PHP upload_max_filesize is <= than atim maxUploadFileSize, problem in uploading' Non-consistent definition of php variables and ATiM variables that will generate an error when uploading file into ATiM. Open the php.ini file and change upload_max_filesize value to a biggest value then restart the server

OR

Open the core.php of the ATiM source code and change core variable maxUploadFileSize to a lowest value.

'warning_PHP post_max_size is <= than upload_max_filesize, problem in uploading' Non-consistent definition of php variables and ATiM variables that will generate an error when uploading file into ATiM. Open the php.ini file and change post_max_size value to a biggest value then restart the server

OR

Open the core.php of the ATiM source code and change core variable upload_max_filesize to a lowest value.

When you enter your valid credential and hit login, you remain on the login page with no error message. When you enter invalid credentials, you have the "Login failed" error message.

OR

Your session ends faster than it should.

Premature cookie expiration. The client (your computer) time is in advance compared to the server time (regardless of the time zones). This difference between the client and the server can reduce your allowed session length or even make it impossible to log to the system. You need to synchronize both systems time. You should also enable automated time synchronizing on both machine to avoid future problems. If you are in a situation where you can't synchronize the system time, setting the client time to a future time should resolve the issue.
The tmp folder cannot be written to. Change the permissions to allow the web server to write to the tmp directory and sub directories.
When reaching ATiM page, an error 500 page or a browser error page is displayed. There is an error in the installation and the output buffer crashes before it can print anything. Turn main output buffering off. Go to app/views/layous/default.ctp and comment ob_start('ob_gzhandler'); and ob_end_flush();. If after that you have no warning message at all, it means that the ob_gzhandler is not installed. Otherwise, keep on debuging.
You have the following warnings. * caching issue. (null) ? ?
You have an error page stating
Notice (8): Undefined variable: shell [APP/views/layouts/default.ctp, line 16]
Fatal error: Call to a member function header() on a non-object in /home/ctrnadmi/public_html/demo/app/views/layouts/default.ctp on line 16
The database is empty. Fill the database with ATiM creation script.
Using Internet Explorer, the top menu is not displayed properly. You're accessing ATiM on the local network, and the compatibility view is activated. In the URL bar, there is an icon representing a sheet of paper teared in two halves. Click on it.
OR
Disable the "Display intranet sites in Compatibility View" option. Go to "Tools" (might be hidden, press the Alt key to show it) and then "Compatibility View Settings".
You have a ton of SplFileInfo::openFile error messages. Your version of PHP is bellow 5.2.6. Upgrade PHP to a version greater or equal to 5.2.6. (PHP 5.3+ is required for ATiM 2.5+)
I have an error caused by too many redirections. Your modrewrite config might be wrong. Check your modrewrite config.
Under Firefox, I can't reach ATiM. The proxy settings might interfere. Go to preferences (possibly under tools) > advanced > network > settings... > and select "no proxy".
In ICD tools, the keyword "right" doesn't work. This keyword is part of a MySQL fulltext search and it's part of the stop words list. See MySQL Full-Text Stopwords
Only a blank white screen is shown. Apache error log shows 'PHP Fatal error: Cannot redeclare config() Missing .htaccess files. Be sure to upload the hidden .htaccess files to the appropriate folders

Verify that mod_rewrite is activated. This link provides instructions.

Under Apache, you are getting this error: require_once(Cake/Controller/Component/Acl/DbAcl.php): failed to open stream: No such file or directory Cake is not in the include path because mod_rewrite is not enabled/working. To confirm this, use phpinfo() function, go to the "Loaded Modules" section and see if mod_rewrite is listed. If not, start from 1. If so, start from 5.
  1. On a linux machine, type: locate mod_rewrite.so.
  2. Then, locate httpd.conf.
  3. Edit the httpd.conf file and add LoadModule rewrite_module {path to mod_rewrite.so}.
  4. Restart apache. (Command: apache2ctl restart)
  5. Then edit /etc/apache2/sites-available/default
  6. Change AllowOverride None to AllowOverride All for your directory context.
You have a similar error

Notice (8): Use of undefined constant csv_separator - assumed 'csv_separator' [CORE\Cake\View\HelperCollection.php, line 88] Notice (8): Undefined property: View::$Shell [CORE\Cake\View\View.php, line 804] Fatal error: Call to a member function header() on a non-object in

Your database configuration is wrong. Verify your datasource parameter is properly configured in database.php
You have a similar error

Notice (8): Use of undefined constant csv_separator - assumed 'csv_separator' [CORE\Cake\View\HelperCollection.php, line 88] Notice (8): Undefined property: View::$Shell [CORE\Cake\View\View.php, line 804] Fatal error: Call to a member function header() on a non-object in

Your are running a old version of ATiM. In PHP version 5.4.19 - developers closed the ability to set session.auto_start option from user script. You can simply comment out a lines ['session.auto_start' => 0,] in /lib/Cake/Model/Datasource/CakeSession.php (around line 557):
CSV export doesn't work. (Possibly an error 500.) PHP was not compiled with multibyte string support. Compile php with the flag --enable-mbstring.
Fatal error during batch action (realiquoting, derivative creation, etc) on set greater than 30 records. The problem may be a low "max_input_vars" php setting.

See: http://stackoverflow.com/questions/10084014/php-json-post-array-is-received-incomplete

Add max_input_vars=5000; to your php.ini
Incomplete batch action (realiquoting, derivative creation, etc) on set greater than 30 records.

Only some of expected records have been created.

The problem may be a low "max_input_vars" php setting.

See: http://stackoverflow.com/questions/10084014/php-json-post-array-is-received-incomplete

Add max_input_vars=5000; to your php.ini
I have a browser error page. Looking at app/tmp/logs/error.log I see Unable to configure the session, setting session.auto_start failed. session.auto_start may not be changed at all times. It is better to turn it on from php.ini. Go to your php.ini file and set session.auto_start = 1. Then restart your webserver.
With apache server you have following message

Database connection “Mysql” is missing, or could not be created

PDO_MYSQL driver has net been activated Uncomment the following line extension=php_pdo_mysql.dll in php.ini
Warning (2): strtotime() [6]: It is not safe to rely on the system's timezone settings. You are required to use the date.timezone setting or the date_default_timezone_set() function. you need to uncomment the line date_default_timezone_set('UTC'); in core.php
Created csv file is empty Or Error: [Error] Call to undefined function mb_convert_encoding() A lot of newer Linux servers do not have PHP Multibyte modules installed by default. A simple solution is often to install php-mbstring.
yum install php-mbstring on centos

Production Environment Recommendations

ATiM database is likely to house confidential health and materials information that cannot be replicated from any other source. Complete loss of this information could result in the stranding of banked biological materials.

Installation of the required computer and related network hardware are a local responsibility. CTRNet provides the following recommendations as a guideline only. They are not intended to replace institutional policy.

Security Requirements

Where ATiM is used to collect, store and present sensitive health information, qualified local expertise and resources are mandatory to ensure that installation meets or exceeds the appropriate institutional policies for handling and protecting sensitive personal data for research purposes.

User Access Recommendations

  • End-user access should be managed by the login and security features provided in ATiM.
  • Access to ATiM application and the related databases should be restricted to personnel trained and authorized to handle personal information on a “need-to-know” basis.
  • User authorities must be documented and configured to meet local needs prior to populating the application with confidential data.

Server Recommendations

  • ATiM database and application servers should run behind a managed institutional firewall intended to protect clinical data.
  • ATiM database and application server accesses should be limited, secured and controlled.
  • A secure connection (SSL connection (https, etc)) is recommended to connect ATiM from any workstation.

Backup Recommendations

  • ATiM and the related databases should be backed up on a daily basis and treated as confidential production data.
  • Off site storage should be completed on a weekly basis.
  • Off site storage access should be limited, secured and controlled.

Prospective Banks Checklist

New biobanks considering use of ATiM should review the following guidelines to help ensure a successful, and timely installation.

IT Support

ATiM is a web-based and highly configurable application. Someone capable of installation, customization and ongoing support of the application will be needed. The skill set required for your IT staff will vary depending on the level of customization, data audits, and/or porting of existing data. Based on previous experience with other banks, CTRNet recommends the following qualifications for your IT support staff:

  • Experience with server administration. (Only applicable if hosting on your own server).
  • General database administration - Understanding of SQL, backup/restoration, ongoing maintenance.
  • Understanding of PHP, specifically the CakePHP framework and/or Model-View-Controller design pattern.

When bank requirements include complex business rules, new plug-ins, or additional functionality knowledge of PHP and general web-development is imperative

ATiM Hardware/Software Requirements

Most banks choose to run ATiM on a dedicated server located in a secure server room environment. Please see section above to learn about the system requirements.

Application Configuration

ATiM was designed based on the requirements of multiple bio-respositories all with differing disease-site specialties. In most applications, the base installation will only require minor customization such as:

  • Setting up dropdown lists with local data such as provider names (Doctors, local hospitals, bank staff)
  • Disabling or hiding sections of the application the bank does not wish to use. For example a bank may only specialize in collecting blood products. All other sample types and related deriviates/aliquots can be hidden from the user.
  • Creating users, groups and assigning appropriate permissions.
  • Basic bank validation rules.

Moderate customization would include:

  • Adding additional aliquot and sample types. See Inventory for a complete listing.
  • Adding new storage types. See Storage Management for a complete listing.
  • Adding new disease site specific events. For example a new lifestyle questionnaire for prostate cancer.

High level customization:

  • Specific business logic to execute. For example complex bank data validation rules to be checked before any new record was saved.

Questions

The process of installation, customization, and loading data from existing data sources (if any) can have a significant impact on timelines for getting ATiM into a production biobank environment. To help banks better understand project timelines, CTRNet has provided a questionnaire to gather information on the prospective installation site. Upon review by CTRNet a general timeframe and project plan can be derived from the responses.

Existing data sources

Objective: Describe all existing data sources that will be ported into the ATiM.

  • Format (Access, Excel, other database types)
  • Data quality - Are fields controlled by constraints and validations rules?
  • Number of records - Small, complex datasets can be re-entered where larger one's must be audited and loaded through scripts
  • Data dictionary and/or ERD - Describe all data elements collected, permissible values for those elements, definitions, etc. An diagram of any database structure would be useful.
Disease sites collected
  • DX Speciality - What types of data are collected for each disease site:
  • Followup
  • Path reports
  • Initial Presentation
  • Treatment
  • Lifestyle
  • Screening
  • Adverse Events
Inventory
  • Sample types collected + related derivatives and aliquots for each type
  • Storage model described
Users Groups and Banks
  • Define list of users, what roles they perform and disease site groups they work with.
Personal tools