1-installation.md

← 0. Annotations in the manual	↑ Index	2. Using GIVE Web Components →

Installation

Table of Contents

• Introduction
• Prerequisites
  • Installing a Web Server
  • Installing PHP
  • Installing a MySQL-compatible Instance
• Installing GIVE Web Components
• Installing GIVE Server
  • Installing GIVE Server-side Components
  • Installing GIVE Data Sources

Introduction

---

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

Prerequisites

Installing a Web Server

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 SimpleHTTPServer module (Windows, Mac OS, Linux supported)

Installing PHP

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:

• PHP installation and configuration
• cURL library

Installing a MySQL-compatible Instance

GIVE also needs a MySQL-compatible instance as a data source. Please refer to the following resources for installing your own MySQL instance:

• MySQL community server
• MariaDB

Installing GIVE Web Components

Copy the contents of /give/html folder to a designated folder on your web server.

The URL to access your designated folder (including the trailing /) on your hosting environment will be referred to as GIVE Web Components Path or web_components_path (in code) throughout the manual and it will be needed when importing GIVE Web Components in your HTML pages.

For example, if your server is accessible from https://www.example.com/ and all files under /give/html/ is copied to /give_components on your server (if you are using Apache in Linux, the folder may be /var/www/html/give_components/, for IIS in Windows, it may be C:\wwwroot\give_components\), then your GIVE Web Components Path or web_components_path will be:

https://www.example.com/give_components/

---

NOTE: A public GIVE server is available at demo.give.genemo.org. If you wish to use GIVE Web Components hosted on the public server, please use https://demo.give.genemo.org/ as your web_components_path

---

Installing GIVE Server

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.

Installing GIVE Server-side Components

Part of GIVE Server-side Components are already included in files under /give/html/ and have been installed with GIVE Web Components. Please put the contents under /give/includes/ somewhere on your server. The files under /give/includes/ does not need to be directly accessed, however, it will be easier if the relative path from /give/html/givdata to /give/include was kept the same.

After installation, please edit /give/html/components/bower_components/genemo-data-components/basic-func/constants.js to indicate the server-side components' location:

give.host = '<web_components_path>'

Installing GIVE Data Sources

To link the MySQL-compatible instance to the server-side component of GIVE, 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:

← 0. Annotations in the manual	↑ Index	2. Using GIVE Web Components →