GOCDB/Regional Module Technical Documentation
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
- 1 Deployment
- 1.1 System prerequisites
- 1.2 Preparing your installation
- 1.2.1 Database preparation
- 1.2.2 Web machine preparation
- 1.2.3 Final check
- 1.3 Running GOCDB-4 setup
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.
- Required database: Oracle 10g or higher (note: Oracle 10g Express edition, which comes with a free license, is perfectly suitable)
- Required space: 150 MB
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
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:
|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
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.