Alert.png The wiki is deprecated and due to be decommissioned by the end of September 2022.
The content is being migrated to other supports, new updates will be ignored and lost.
If needed you can get in touch with EGI SDIS team using operations @ egi.eu.

GOCDB/Regional Module Technical Documentation

From EGIWiki
< GOCDB
Revision as of 15:31, 17 November 2010 by Aesch (talk | contribs) (→‎Final check)
Jump to navigation Jump to search

This page is the main technical documentation for GOCDB-4 regional module

SUPPORTED VERSION: GOCDB-4.0.d7 - build GOCDB-4.0-4.d7.noarch

Deployment

System prerequisites

GOCDB-4 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

  • Required database: Oracle 10g or higher (note: Oracle 10g Express edition, which comes with a free license, is perfectly suitable)
  • Required space: 150 MB

Web frontend

The machine to use as the web frontend will need the following:

  • Apache http server version 2.0 or higher.
  • PHP version 5.2 or higher.
    • PHP oci8 extension
    • libxml2 and DOM support for PHP (Note: On RHEL, PHP requires the PHP XML RPM to be installed for this component to function).
    • OpenSSL Extension for PHP
  • Oracle Instant client version 10 or higher (downloadable from Oracle website)
  • a X509 host certificate for the machine

Preparing your installation

Database preparation

Important note: This section needs to be executed by Database System Administrators.

  • If you don't have admin rights on the DB you are using, please contact your DBAs with the instructions contained in this section.
1- Create tablespaces for GOCDB

GOCDB-4 database contains 3 distinct groups of tables: Metadata or core data, GOCDB data, and local data. Although this is not mandatory, we recommend that 3 different tablespaces be created to store these different tables:

Tablespace Size Purpose
TS_GRIDCORE 50m Will store the core tables containing schema metadata
TS_GOCDBDATA  50m  Will store GOCDB data tables (common structure to all GOCDB modules)
TS_LOCALDATA  50m  Will store your local tables if you have some local information to store

Note: Choose whatever names you want for your tablespaces. You'll be able to configure the system to use whatever names your tablespaces have.

2- Create a DB user for GOCDB

Any existing user is OK but we advise that a user be dedicated to run GOCDB.

  • Grant access and unlimited quotas to your GOCDB user on previously defined tablespaces.
3- Manage user privileges

Grant the following privileges to your GOCDB user:

  • CREATE SESSION
  • CREATE TABLE
  • CREATE TYPE
  • CREATE SEQUENCE
  • CREATE TRIGGER
  • CREATE PROCEDURE
  • CREATE MATERIALIZED VIEW
  • CREATE JOB

Web machine preparation

1- install host certificate for the machine
  • GOCDB web portal component needs the machine to run a https server which requires a server X509 certificate. Please check that Apache is properly configured to use the installed server certificate. Help about how to set up SSL configuration on Apache can be obtained from Apache mod_ssl online documentation.
2- Get and deploy GOCDB-4 code package
  • download GOCDB-4 regional package from: https://www.sysadmin.hep.ac.uk/svn/grid-monitoring/tags/gocdb/GOCDB-4.0d7_distrib/RPM/
  • Install the GOCDB-4 RPM (rpm -i GOCDB-4.0-4.d7.noarch.rpm)
  • Verify the user running httpd has read access to the directories/files. The files are often not accessible by the Apache user by default. (Default installation location: /usr/share/GOCDB)
  • Create the following Apache Aliases (or set up virtual hosts)
    • Alias "/portal" "/usr/share/GOCDB/htdocs/web_portal"
    • Alias "/admin" "/usr/share/GOCDB/htdocs/admin"
    • Alias "/xml_input" "/usr/share/GOCDB/htdocs/xml_input"
  • Configure Apache to use SSL and client certificate verification for the web portal section of the site. The user certificate DN's are used for authentication to the web front end.
  • Ensure the web server port is open on your machine. As a first step, you probably want the port to be open internally only (giving the whole wide world access to your GOCDB admin page is probably not a good idea)
  • Restart Apache so that the new aliases are loaded from the configuration file.
  • Check that the pages can be correctly accessed by browsing to the newly created "admin" alias. Note that the system is not yet fully set up and will not work!

Note: Creating and managing http aliases is part of Apache http server handling. Please check Apache documentation if you need details.

3- Create and edit prom.conf configuration file
  • Rename or copy /usr/share/GOCDB/config/prom.conf_TEMPLATE to /usr/share/GOCDB/config/prom.conf
  • Edit prom.conf. Under the [Oracle_server] section, specify the connection details to your DB. "host" can be a simple hostname or a full connection string (see examples below).

All settings must be enclosed in quotation marks.

example 1: Specifying a simple hostname

host="dbhostname.domain.org"
port="1521"
database="Database_Name" 
user="GOCDB_USER"
password="gocDBpassWord"

example 2: Specifying a connection string (warning: the whole string has to be on one single line) )

host="(DESCRIPTION=(LOAD_BALANCE=yes)(FAILOVER=ON)(ADDRESS=(PROTOCOL=TCP)(HOST=dbhostname1.domain.org)\\
   (PORT = 1521))(ADDRESS = (PROTOCOL = TCP)(HOST = dbhostname2.domain.org)(PORT = 1521))\\
   (CONNECT_DATA=(SERVICE_NAME=gocdb.domain.com)(FAILOVER_MODE=(TYPE=SESSION)(METHOD=BASIC))))"
port=
database= 
user="GOCDB_USER"
password="gocDBpassWord"
4- Create and edit local_info.xml configuration file
  • Rename or copy /usr/share/GOCDB/config/local_info.xml_TEMPLATE to /usr/share/GOCDB/config/local_info.xml
  • Edit local_info.xml whith the following information:
    • tablespace names, as configured in the previous section
    • Collection ID, which is a unique ID that will eventually be used to distinguish different GOCDB regional instances. Currently this should be left as 0.
    • instance type, which can be either "central" or "regional". This should be set to regional.
    • web_portal_url, which is the full url of your GOCDB web portal as defined during the setup process above
5- Create and edit local_schema.xml configuration file
  • Rename or copy /usr/share/GOCDB/config/local_schema.xml_TEMPLATE to /usr/share/GOCDB/config/local_schema.xml
  • You don't need to edit/modify this file now. How to use this file (and why) will be described in the Customisation section

Final check

If you have carefully followed all the previous steps, you should now have:

  • An Oracle database where GOCDB will run, with connection details and proper privileges
  • A web machine that will host GOCDB front end
  • On the web machine, the following configuration files appropriately edited:
    • /usr/share/GOCDB/config/prom.conf, with proper database connection details
    • /usr/share/GOCDB/config/local_info.xml, with proper tablespace information and your assigned collection id
    • /usr/share/GOCDB/config/local_schema.xml, left as it is for now (content doesn't matter for the setup process as long as the file is here)
  • An alias to GOCDB admin web page, available through your browser.
  • An alias to GOCDB web front end, available through your browser.
  • An alias to GOCDB xml input, available through your browser.

And now the moment of truth...

  • Open GOCDB admin web page in your browser (yes, the alias you have defined above)
  • On the welcome page, click on the configuration check link
    • If it says "your settings look fine", congratulations, you are ready to go to the next step and deploy GOCDB!
    • If not, displayed error message should tell you what has gone wrong. Go through the preparation steps again and perform a configuration check until you have solved all problems

Running GOCDB-4 setup

If you have followed all the steps of the previous section, have reached the "final check" step and have managed to display a nice "your settings look fine" on a web page, then deploying GOCDB-4 is one of the simplest things on earth:

  • Open GOCDB admin web page in your browser
  • Browse to the Main Admin Menu
  • Click on the Deploy and setup GOCDB for the first time link
  • Click on the start deployment button
  • The system will then go through a configuration check again, and should display a success message (if not, then you've not followed previous steps properly!)
  • Click on the deploy now button
    • If you've got a success message then congratulations! You have successfully deployed GOCDB-4. Now browse to the "Administration" section for next steps
    • If you receive any error messages, please browse to the errors and troubleshooting section.