NOTE: Installation of GIVE is optional and not required to use any of the Web Components of GIVE. By installing GIVE components, you can serve codes and/or data sources directly from your own server.
GIVE consists of two major parts:
- GIVE Web Components, the client-side codes running in browsers, implemented by HTML5;
- GIVE server, this can be any server that is compatible with GIVE Web Components. The source code on GIVE repository, and the implementation on
give.genemo.org, include two parts:- GIVE server-side component, implemented by PHP
- GIVE data sources
Clone GIVE from Github to your computer/server to get the source code:
git clone https://github.com/Zhong-Lab-UCSD/Genomic-Interactive-Visualization-Engine.git
To install any part of GIVE, a web-hosting environment is needed on your server. Please refer to the following information for how to install a web server on your OS:
- Apache Server (Windows and Linux supported, also included in Mac OS)
- NGINX (Windows and Linux supported, Mac OS support needs additional work)
- Internet Information Services (IIS) (Included in Windows)
- Python
SimpleHTTPServermodule (Windows, Mac OS, Linux supported)
NOTE: After installation, the URL to access your web server will be referred to as give_host later in the manual. You can use empty string if you plan to put your GIVE Server and GIVE Web Components under the same host.
*NOTE: This part is only required if you would like to install your own GIVE Server.
The server-side component of GIVE requires a functional PHP (7.0 or higher) web server with cURL support to work. Please refer to the following instructions to install PHP and cURL module to your web server:
*NOTE: This part is only required if you would like to install your own GIVE Server.
GIVE also needs a MySQL-compatible instance as a data source. Please refer to the following resources for installing your own MySQL instance:
Due to security concerns, we would recommend you create a dedicated user (instead of root) on the instance for GIVE Server.
NOTE: The user will be referred to as GIVE Database User, its user name as give_data_user, and its password as give_data_pass.
GIVE Database User needs to have the following privileges to function properly:
| Privilege(s) | Database.Table |
|---|---|
SELECT, CREATE TEMPORARY TABLES |
`compbrowser`.* |
SELECT, CREATE TEMPORARY TABLES |
`<your_reference_databases>`.* (See manual 3.2. MySQL commands for managing data in GIVE data source for a detailed description of reference databases.) |
The SQL code to grant the privileges is shown below:
GRANT SELECT, CREATE TEMPORARY TABLES ON `compbrowser`.* TO `<give_data_user>`@'%'; GRANT SELECT, CREATE TEMPORARY TABLES ON `<your_reference_database>`.* TO `<give_data_user>`@'%'; -- please do this for each of your reference database
NOTE: You can simply grant those privileges on *.*, although this may increase the damage if your GIVE Database User gets compromised. If you determine to do this (please take necessary measures), you can use the following SQL code at the MySQL console:
GRANT SELECT, CREATE TEMPORARY TABLES ON *.* TO `<give_data_user>`@'%';
NOTE: This is completely optional if you don't want to link GIVE to your own data sources. If you wish to use the public GIVE Server hosted at www.givengine.org, please use https://www.givengine.org/ as your web_components_path when installing your GIVE Web Components.
GIVE server consists of two parts: GIVE server-side component, which serves as interfaces between GIVE Web Components and the data sources, and the data sources themselves.
Copy everything under /html/givdata/ and /includes/ somewhere on your server. The files under /includes/ does not need to be directly accessed from the web server (and it will be preferable to keep it inaccessible for security reason), however, it will be easier if the relative path from /html/givdata to /includes was kept the same.
NOTE: The file system path where you put /includes/ on your server (including the leading and trailing /'s or \'s, same below for all paths, for example, /var/www/includes/) will be referred to as include_path, and the URL path where you can access /html/givdata/ online (for example, /givdata/) from a browser will be referred to as give_server_path.
You will then need to configure the PHP component and link GIVE Server to the MySQL-compatible instance, by editing the configuration file in GIVE Server. Please make a copy of constants_template.php under your include_path and edit the following lines to provide the necessary information:
define('CPB_HOST', '<your_mysql_host>');
define('CPB_USER', '<give_data_user>');
define('CPB_PASS', '<give_data_pass>');
define('CLASS_DIR', '<include_path>classes');
define('GOOGLE_ANALYTICS_ACCOUNT', '<your_google_analytics_id>');
When you are done, rename it to constants.php so GIVE Server can access your data source.
A database named compbrowser with a table named ref need to be created on the instance. The ref table is used to tell engine what references are available to be displayed and it needs at least the following columns:
| Column name | Type | Description |
|---|---|---|
dbname |
varchar |
The reference database name, only alphanumerics ([0-9A-Za-z]) and underscores (_) are allowed, e.g. hg38. Note: this value will be used in the other tables/databases and be referred to as the reference database name or your_reference_database in the future. |
name |
varchar |
The formal name of the species, can be the Latin name, e.g. Homo sapiens. |
commonname |
varchar |
The common name of the species, e.g. human. |
browserActive |
tinyint |
Whether this reference is active for GIVE, use 1 to indicate it's active. |
settings |
longtext |
Additional settings and tags related to the reference, this should be a string in JSON format. |
The following SQL code can be used to create a ref table in
a new compbrowser database.
CREATE TABLE `compbrowser`.`ref` (
`dbname` varchar(30) NOT NULL DEFAULT '',
`name` varchar(100) DEFAULT NULL,
`commonname` varchar(50) DEFAULT NULL,
`browserActive` tinyint(1) NOT NULL DEFAULT '0',
`settings` longtext NOT NULL,
PRIMARY KEY (`dbname`)
)
The data structure is illustrated as below:
Copy both /html/components folder and /html/bower_components folder to a designated folder on your web server.
NOTE: The URL path where your /html/components folder can be accessed online on your hosting environment will be referred to as web_components_path and the URL path where your /html/bower_components folder can be accessed online will be referred to as bower_components_path throughout the manual.
The web_components_path will be needed when importing GIVE Web Components in your HTML pages.
After installation, please make a copy of <web_components_path>/basic-func/constants-template.js to indicate the server-side components' location:
give.Host = '<give_host>' give.ServerPath = '<give_server_path>'
Rename your copy to constants.js under the name path to apply the settings.