Difference between revisions of "GOCDB/Regional Module Technical Documentation"
Line 1: | Line 1: | ||
{{Template:Op menubar}} {{Template:GOCDB_menubar}} {{TOC_top}} This page is the main install documentation for GOCDB | {{Template:Op menubar}} {{Template:GOCDB_menubar}} {{TOC_top}} This page is the main install documentation for GOCDB Version 5 | ||
== Download == | == Download == | ||
Line 18: | Line 18: | ||
*https://wiki.egi.eu/wiki/GOCDB/v4/Regional_Module_Technical_Documentation | *https://wiki.egi.eu/wiki/GOCDB/v4/Regional_Module_Technical_Documentation | ||
<!--- | <br> | ||
<!--- | |||
== Deployment == | == Deployment == | ||
Line 52: | Line 54: | ||
=== Database preparation === | === Database preparation === | ||
For Dave :) | |||
=== GOCDB file system === | |||
Place the GocDB source folder on your chosen web server. | |||
=== PEAR === | === PEAR === | ||
Pear is recommended to install Doctrine and PHPUnit, many builds of PHP come pre-bundled with PEAR. | Pear is recommended to install Doctrine and PHPUnit, many builds of PHP come pre-bundled with PEAR. | ||
Line 84: | Line 90: | ||
=== Apache === | === Apache === | ||
///// | |||
=== PHPUnit === | |||
PHPUnit is an optional choice for GOCDB users. GOCDB5 includes a test suite of unit tests that can be used to verify buisness logic and database connections for a deployed instance of GOCDB. In addition developers extending and modifying GOCDB can write unit tests for their own developements. To install PHPUnit use PEAR: | |||
<pre>$pear clear-cache | |||
$pear config-set auto_discover 1 | |||
$pear install pear.phpunit.de/PHPUnit | |||
</pre> | |||
This install can then be verified using "phpunit --version" on the command line: | |||
<pre>$ phpunit --version | |||
PHPUnit 3.7.27 by Sebastian Bergmann. | |||
</pre> | |||
== Deploying GOCDB5 == | |||
=== Configuration of the database connection === | |||
You should now have all the required blocks in place to deploy GOCDB V5. To Deploy the database schema to your desired database using Doctrine navigate to to gocDBSrc/lib/Doctrine/Deploy folder. In this folder you will configure the database connection details for your database. Depending on the type of database you are using open the bootstrap_doctrine.php file your database: | |||
<pre>bootstrap_doctrine.php.mysql -> For MySQL databases | |||
bootstrap_doctrine.php.oci -> For Oracle databases | |||
bootstrap_doctrine.php.sqlite -> For SQLite databases | |||
</pre> | |||
In the bootstrap_doctrine file complete the connection details for your database. | |||
For Oracle: | |||
<pre>$conn = array( | |||
'driver' => 'oci8', | |||
'user' => 'doctrine', | |||
'password' => 'doc', | |||
'host' => 'localhost', | |||
'port' => 1521, | |||
'dbname' => 'XE' | |||
); | |||
</pre> | |||
For MySQL: | |||
<pre>$conn = array( | |||
'driver' => 'pdo_mysql', | |||
'user' => 'Doctrine', | |||
'password' => 'doc', | |||
'host' => '127.0.0.1', | |||
'dbname' => 'doctrine' | |||
); | |||
</pre> | |||
For SQLite: | |||
<pre>$conn = array( | |||
'driver' => 'pdo_sqlite', | |||
'path' => __DIR__ . '/db.sqlite', | |||
); | |||
</pre> | |||
Note: Doctrine can use APC caching however this is not suitable for all deployments. To disable comment out the APC configuration lines within the bootstrap_doctrine.php file: | |||
<pre>$config->setMetadataCacheImpl(new \Doctrine\Common\Cache\ApcCache()); | |||
$config->setQueryCacheImpl(new \Doctrine\Common\Cache\ApcCache()); | |||
</pre> | |||
=== Deploying GOCDB === | |||
To deploy GOCDB execute the deploy file for your database found in the deploy folder. | |||
<pre>gocDBSrc/lib/Doctrine/deploy/oracleDeploy.sh | |||
gocDBSrc/lib/Doctrine/deploy/mysqlDeploy.sh | |||
gocDBSrc/lib/Doctrine/deploy/sqlite.sh | |||
</pre> | |||
Within the source code you will also find a set of sample data to deploy with GOCDB. To deploy this data specify the location of the sample data folder when deploying: | |||
<pre>$./oracleDeploy.sh sampleData/ | |||
</pre> | |||
This will begin the process of deploying the database scheme and data if provided to your database. | |||
=== Apache Configuration === | |||
==== httpd.conf ==== | |||
Now that your database is deployed the final step is to configure Apache. | |||
A few modules need to be enabled for GOCDB to work, check these are enabled on your Apache and if not enable them. | A few modules need to be enabled for GOCDB to work, check these are enabled on your Apache and if not enable them. | ||
In httpd.conf enable ssl_module by un-commenting these lines: | In ''httpd.conf'' enable ssl_module by un-commenting these lines: | ||
<pre>LoadModule ssl_module modules/mod_ssl.so</pre> | <pre>LoadModule ssl_module modules/mod_ssl.so</pre> | ||
and | and | ||
<pre>extension=php_openssl.dll</pre> | <pre>extension=php_openssl.dll</pre> | ||
Depending on the database you are using the supporting module may also need to be enabled. For example Oracle requires: | Depending on the database you are using the supporting module may also need to be enabled. For example Oracle requires the oracle module to be uncommented: | ||
<pre>extension=php_oci8_11g.dll</pre> | <pre>extension=php_oci8_11g.dll</pre> | ||
< | Take the file ''gocdbssl.conf'' and place this file in the apache/conf/extra folder. In ''httpd.conf'' include the ''gocdbssl.con'' by adding the following line under the heading ''Supplemental Configuration'': | ||
<pre>Include conf/extra/gocdbssl.conf | |||
</pre> | |||
==== gocdbssl.conf ==== | |||
This file defines the location of resources required by GocDB. | |||
===== Paths ===== | |||
The first step is to setup the paths for the ''DocumentRoot, ErrorLog and TransferLog'' and define the ''ServerName'' and ''ServerAdmin'' details for your particular web service where you are hosting GocDB. | |||
===== SSL Keys ===== | |||
The ''SSLCertificateFile'' should point to the location of your server SSL key file. The ''SSLCertificateKeyFile'' -- The ''SSLCACertificationPath'' should point to the location of your CA certificates which can be obtained from: //Ask Dave | |||
For development the ''SSLCertificatedFile'' and ''SSLCertificateKeyFile'' can be self signed certificates. However these must not be used in production. | |||
===== Aliases ===== | |||
The final step is to set the Alias to map your desired directory for GocDB webportal and Programmatic Interface (PI) to the correct folder and ensure the correct rules are defined for your server. | |||
For the webportal the following settings are an example: | |||
<pre> | <pre> Alias "/GocDBWebPortal" "\gocDBsrc\htdocs\web_portal" | ||
<Directory "\gocDBsrc\htdocs\web_portal"> | |||
SSLVerifyClient require | |||
Options FollowSymLinks Indexes | |||
Order deny,allow | |||
Allow from 127.0.0.1 | |||
deny from all | |||
</Directory> | |||
</pre> | |||
The alias should and file location should also be set for the public PI and private PI. Public PI: | |||
<pre>Alias "/doc/public" "\gocDBsrc\htdocs\PI\public" | |||
<Directory "\gocDBsrc\htdocs\PI\public"> | |||
</pre> | </pre> | ||
Private PI: | |||
<pre> | <pre>Alias "/doc/private" "\gocDBsrc\htdocs\PI\private" | ||
<Directory "\gocDBsrc\htdocs\PI\private"> | |||
</pre> | </pre> | ||
[[Category:GOCDB]] | === First Use === | ||
You should now be able to navigate to the GocDB webportal on your host using the URL defined in your alias. You will need to install a browser certificate that is suitable for the SSL keys you defined for your host to be able to view GocDB. | |||
[[Category:GOCDB]] |
Revision as of 11:16, 6 November 2013
Main | EGI.eu operations services | Support | Documentation | Tools | Activities | Performance | Technology | Catch-all Services | Resource Allocation | Security |
GOC DB menu: | Home • | Documentation Index • |
This page is the main install documentation for GOCDB Version 5
Download
LATEST VERSION: GOCDBv5
- Install docs for V5 comming soon.
- A packaged V5 release will also be made available for download soon.
- In the meantime, early adopters can check out the v5 src from svn:
svn checkout https://www.sysadmin.hep.ac.uk/svn/grid-monitoring/branches/gocdb/Doctrine%20Web%20Portal
Note, if you are asked to authenticate with a client certificate as below, you can dismiss by pressing Enter
Authentication realm: https://www.sysadmin.hep.ac.uk:443 Client certificate filename: <ENTER to dismiss>
OLD v4.4 Install doc has been relocated
<!---
Deployment
System prerequisites
GOCDB-5 regional module has two components: a database and a web front end. Both components can work on the same machine but it is very likely that in most environments they will be separated. This is what we would advise anyway. Machine requirements for these 2 components are described below.
Database
- Mysql/Oracle/Sqlite
Web frontend
The machine to use as the web frontend will need the following:
- Apache http server version 2.2 or higher.
- PHP version 5.3 or higher (version <=5.2 has some OOP related bugs).
- PHP oci8 extension
- PHP oci8 extension
- a X509 host certificate for the machine
Optional
- PHP Unit for testing developments
Preparing your installation
Database preparation
For Dave :)
GOCDB file system
Place the GocDB source folder on your chosen web server.
PEAR
Pear is recommended to install Doctrine and PHPUnit, many builds of PHP come pre-bundled with PEAR.
http://pear.php.net/manual/en/installation.getting.php
Verify the PEAR installation by running pear version on the command line.
$ pear version PEAR Version: 1.9.4 PHP Version: 5.3.8 Zend Engine Version: 2.3.0 Running on: Windows NT ESCPC0095 6.1 build 7601 (Windows 7 Business Edition Service Pack 1) i586
Doctrine
Doctrine can be installed using PEAR. First add the Doctrine and Symfony channels to PEAR:
$pear channel-discover pear.doctrine-project.org $pear channel-discover pear.symfony.com
Then install Doctrine and it's dependencies:
$pear install --alldeps doctrine/DoctrineORM
Verify the Doctrine installation by running "doctrine --version" on the command line:
$ doctrine --version Doctrine Command Line Interface version 2.3.3
See the possible errors and troubleshooting section if you encounter errors at this point.
Apache
/////
PHPUnit
PHPUnit is an optional choice for GOCDB users. GOCDB5 includes a test suite of unit tests that can be used to verify buisness logic and database connections for a deployed instance of GOCDB. In addition developers extending and modifying GOCDB can write unit tests for their own developements. To install PHPUnit use PEAR:
$pear clear-cache $pear config-set auto_discover 1 $pear install pear.phpunit.de/PHPUnit
This install can then be verified using "phpunit --version" on the command line:
$ phpunit --version PHPUnit 3.7.27 by Sebastian Bergmann.
Deploying GOCDB5
Configuration of the database connection
You should now have all the required blocks in place to deploy GOCDB V5. To Deploy the database schema to your desired database using Doctrine navigate to to gocDBSrc/lib/Doctrine/Deploy folder. In this folder you will configure the database connection details for your database. Depending on the type of database you are using open the bootstrap_doctrine.php file your database:
bootstrap_doctrine.php.mysql -> For MySQL databases bootstrap_doctrine.php.oci -> For Oracle databases bootstrap_doctrine.php.sqlite -> For SQLite databases
In the bootstrap_doctrine file complete the connection details for your database.
For Oracle:
$conn = array( 'driver' => 'oci8', 'user' => 'doctrine', 'password' => 'doc', 'host' => 'localhost', 'port' => 1521, 'dbname' => 'XE' );
For MySQL:
$conn = array( 'driver' => 'pdo_mysql', 'user' => 'Doctrine', 'password' => 'doc', 'host' => '127.0.0.1', 'dbname' => 'doctrine' );
For SQLite:
$conn = array( 'driver' => 'pdo_sqlite', 'path' => __DIR__ . '/db.sqlite', );
Note: Doctrine can use APC caching however this is not suitable for all deployments. To disable comment out the APC configuration lines within the bootstrap_doctrine.php file:
$config->setMetadataCacheImpl(new \Doctrine\Common\Cache\ApcCache()); $config->setQueryCacheImpl(new \Doctrine\Common\Cache\ApcCache());
Deploying GOCDB
To deploy GOCDB execute the deploy file for your database found in the deploy folder.
gocDBSrc/lib/Doctrine/deploy/oracleDeploy.sh gocDBSrc/lib/Doctrine/deploy/mysqlDeploy.sh gocDBSrc/lib/Doctrine/deploy/sqlite.sh
Within the source code you will also find a set of sample data to deploy with GOCDB. To deploy this data specify the location of the sample data folder when deploying:
$./oracleDeploy.sh sampleData/
This will begin the process of deploying the database scheme and data if provided to your database.
Apache Configuration
httpd.conf
Now that your database is deployed the final step is to configure Apache.
A few modules need to be enabled for GOCDB to work, check these are enabled on your Apache and if not enable them.
In httpd.conf enable ssl_module by un-commenting these lines:
LoadModule ssl_module modules/mod_ssl.so
and
extension=php_openssl.dll
Depending on the database you are using the supporting module may also need to be enabled. For example Oracle requires the oracle module to be uncommented:
extension=php_oci8_11g.dll
Take the file gocdbssl.conf and place this file in the apache/conf/extra folder. In httpd.conf include the gocdbssl.con by adding the following line under the heading Supplemental Configuration:
Include conf/extra/gocdbssl.conf
gocdbssl.conf
This file defines the location of resources required by GocDB.
Paths
The first step is to setup the paths for the DocumentRoot, ErrorLog and TransferLog and define the ServerName and ServerAdmin details for your particular web service where you are hosting GocDB.
SSL Keys
The SSLCertificateFile should point to the location of your server SSL key file. The SSLCertificateKeyFile -- The SSLCACertificationPath should point to the location of your CA certificates which can be obtained from: //Ask Dave
For development the SSLCertificatedFile and SSLCertificateKeyFile can be self signed certificates. However these must not be used in production.
Aliases
The final step is to set the Alias to map your desired directory for GocDB webportal and Programmatic Interface (PI) to the correct folder and ensure the correct rules are defined for your server.
For the webportal the following settings are an example:
Alias "/GocDBWebPortal" "\gocDBsrc\htdocs\web_portal" <Directory "\gocDBsrc\htdocs\web_portal"> SSLVerifyClient require Options FollowSymLinks Indexes Order deny,allow Allow from 127.0.0.1 deny from all </Directory>
The alias should and file location should also be set for the public PI and private PI. Public PI:
Alias "/doc/public" "\gocDBsrc\htdocs\PI\public" <Directory "\gocDBsrc\htdocs\PI\public">
Private PI:
Alias "/doc/private" "\gocDBsrc\htdocs\PI\private" <Directory "\gocDBsrc\htdocs\PI\private">
First Use
You should now be able to navigate to the GocDB webportal on your host using the URL defined in your alias. You will need to install a browser certificate that is suitable for the SSL keys you defined for your host to be able to view GocDB.