Node Installation Guide

These installation instructions assume you are using a unix-based operating system and are installing the production version of the code.

Create user

Decide on which user account will run the cron jobs and other administrative tasks. Most likely you will want a dedicated gaia user (and is assumed by the installation instructions). The user you choose must have access to the GAIA database.

Install and configure GAIA software

Decide where you wish to install the software. Most linux installations place web server files in /var/www. The default installation directory for GAIA is /var/www/gaia. The instructions below assume you install into the default directory. If you install elsewhere then change references to /var/www/gaia as appropriate.

As root:

mkdir /var/www/gaia
chown gaia /var/www/gaia

Unless stated otherwise all commands below should be run as user gaia. Obtain GAIA source files

svn co http://svn.gaia-vxo.org/svn/gaia /var/www/gaia/svn

If your network configuration requires you to use a web proxy server (web cache) then you must configure subversion to use it. On a Linux/unix system you must edit ~gaia/.subversion/servers to include your proxy details. See http://subversion.tigris.org/faq.html#proxy for more details.

Create the configuration directories:

mkdir /var/www/gaia/conf
mkdir /var/www/gaia/conf/apache.conf

Create a server configuration file. First copy the template:

cp /var/www/gaia/svn/trunk/public_html/inc/server_config_template.php /var/www/gaia/conf/server_config.php

The use your favourite editor to modify the file as appropriate, for example:

emacs /var/www/gaia/conf/server_config.php

Alter the database passwords. You will need the passwords later when configuring the database accounts.

Alter other settings to suit your installation. Most users will need to configure a database post-install script to install the earthdistance function. Copy the example script from /var/www/gaia/svn/trunk/bin/add_earthdistance_to_db to somewhere permament, e.g,

cp -a /var/www/gaia/svn/trunk/bin/add_earthdistance_to_db /usr/local/sbin/add_earthdistance_to_db

Edit the script to suit your installation. Then edit /var/www/gaia/conf/server_config.php to set db_post_install_cmd to the full name of the script.

Remember to modify your sudoers file to include the necessary permissions so that the unix gaia user can execute the script as the unix postgres user.

Use visudo to edit the sudoers file, it checks syntax before committing the changes. If you are not a vi user visudo will honour your VISUAL or EDITOR environment variables.

Configure Apache

Generate the Apache server configuration file. The GAIA software can do this for you:

php /var/www/gaia/svn/trunk/public_html/inc/generate_apache_config.php > /var/www/gaia/conf/apache.conf/10_gaia.conf

You can then either edit Apache's master configuration file and use an Include directive to read the contents of 10_gaia.conf or insert the contents of 10_gaia.conf manually.

If you use the Apache directive Include /var/www/gaia/conf/apache.conf/*.conf then Apache will include all of the configuration files in /var/www/gaia/conf/apache.conf (in alphabetic order). If you need additional configuration details to be included (either before or after 10_gaia.conf) you can simply create extra files in /var/www/gaia/conf/apache.conf.

To ensure the security of your webserver the files in /var/www/gaia/conf/apache.conf should be owned by root or a trusted user. As root:

chown -R root.apache /var/www/gaia/conf/apache.conf
chmod u=rwx,g=rx,o= /var/www/gaia/conf/apache.conf
chmod -R u=rwX,g=rX,o= /var/www/gaia/conf/apache.conf

For Ubuntu systems you may need to use the www-data instead of apache.

Do not use apache as the trusted user (or whatever user the web server runs as), otherwise PHP scripts may have permission to alter the config file.

If you wish to write your own configuration file for Apache (not recommended) you should note the following points:

• The DocumentRoot should be set to /vaw/www/gaia/svn/trunk/public_html.
• MultiViews must be enabled.
• The directory /vaw/www/gaia/svn/trunk/public_html/inc should not be accessible via HTTP.

Enable required Apache modules

The following Apache modules should normally be enabled; the generate_apache_config.php script assumes that these modules are enabled:

• deflate
• expires

Ubuntu users can simply enable these commands (as root):

a2enmod deflate
a2enmod expires

Restart the web server (as root).

Configure PHP

The GAIA software has been designed to avoid needing PHP settings which most security-conscious webmasters would turn off. See the separate PhpSecuritySettings page for more details.

Compile C programs

Most of the GAIA software uses PHP but a few programs are written in C and must be compiled:

mkdir /var/www/gaia/bin
cd /var/www/gaia/svn/trunk/src
make install

If your node will be hosting datasets which generate CDF plots then you must also build some additional programs. Ensure that the CDF environment variables are set before running make. echo $CDF_BASE should print the directory where CDF is installed. If it does not then source the appropriate files from the CDF directory, (eg if you are using a Bourne shell and CDF is installed in /usr/local/cdf-3.1 then run source /usr/local/cdf-3.1/bin/definitions.B). To compile and install the extra programs:

mkdir /var/www/gaia/bin
cd /var/www/gaia/svn/trunk/src
make install_cdf

CDF versions earlier than 3.2.1 have a buffer overflow vulnerability. Be sure to use a CDF version >= 3.2.1.

Database accounts

Make sure you have installed the contributed PostgreSQL functions!

Create a database account for user gaia, for read and write access to the GAIA database; ensure the database account has permission to create new databases. When prompted enter the password for read-write access you set in server_config.php. The createuser commands below should be run from a user account with PostgreSQL superuser status (typically postgres).

createuser -d -E -P gaia

Create a second account (gaia_ro) for read-only access to the GAIA database; ensure the database account does not have permission to create new databases. This account will be used for most web services. When prompted enter the password for read-only access you set in server_config.php.

createuser -D -E -P gaia_ro

If you do not use the user names listed above you will have problems with the database replication.

If the database is hosted on a remote server you will need to create a password file for psql and createdb. As the gaia user create the file ~/.pgpass using your favourite editor, for example:

emacs ~/.pgpass

Inside the file insert the following text:

hostname:port:*:gaia:password
hostname:port:*:gaia_ro:rpassword_ro

Replace hostname and port with the hostname and port of the database server. Replace password and=password_ro= by the passwords you chose for the gaia and gaia_ro database users.

Ensure others cannot read the file:

chmod go= ~/.pgpass

Install the PL/pgSQL trusted procedural language

GAIA makes use of some server-side functions in the PL/pgSQL procedural language, install into the template1 template by executing the following command as user postgres:

createlang plpgsql template1

New databases will automatically inherit the PL/pgSQL trusted procedural language.

Installation of GAIA database

Create an empty file where the GAIA database name will be stored. Create directory for the data dump files.

touch /var/www/gaia/conf/gaia_db_name.php
mkdir /var/www/gaia/db_dumps

Initialise the installation by fetching the latest database dump from from the node holding the master copy of the database:

/var/www/gaia/svn/trunk/public_html/inc/init_installation.php -H calgary.canada.gaia-vxo.org -r 2873

You may need to set the -p and/or -r options if a non-standard HTTP port and/or rsyncd port is in use on the master node.

Define the master.gaia-vxo.org hostname alias.

Check the installation is correct by attempting to download the latest database:

/var/www/gaia/svn/trunk/public_html/inc/update_database.php -v

If the installation is correct then the line "Database has not changed since last update" will be printed. If you are unlucky and the database has changed since you installed the initial version then the line "Created new database ..." will be printed.

Do not be alarmed if you see warnings that old databases could not be dropped because they are in use, it is perfectly normal behaviour when persistent connections are used. The old databases will be dropped at a later date when the persistent connections have timed out. It is also possible (but much less likely) that the same behaviour is seen when non-persistent connections are used.

You may see the update script crashing out with Segmentation fault (core dumped). The reason for this error has not yet been established. Provided that the word "Done" has been printed you can be sure that all the necessary actions have been completed, in which case please ignore the error.

Cron jobs

Generate the crontab file:

/var/www/gaia/svn/trunk/public_html/inc/generate_crontab.php > /tmp/gaia.cron

Create a new crontab using cron -e, and then insert /tmp/gaia.cron.

Gentoo linux users will need to add the gaia user to the cron group before crontab can be used. This can be done as gpasswd -a gaia cron.

rsyncd configuration

Generate the rsyncd configuration file:

/var/www/gaia/svn/trunk/public_html/inc/generate_rsyncd_conf.php > /tmp/rsyncd.conf

Copy the /tmp/rsyncd.conf into the standard location (probably /etc/rsyncd.conf), or merge the appropriate parts with an existing configuration file.

Please use the default port of 873 if at all possible, otherwise it will prevent your node from ever hosting the master copy of the GAIA database.

If you are already running an rsyncd daemon it is trivial to run more than one instance, with a completely different configuration on a different port.

Debian and Ubuntu linux users will probably need to edit /etc/default/rsync to change the line

RSYNC_ENABLE=false

to

RSYNC_ENABLE=true

Notify the GAIA adminstrators

Congratulations, your installation is complete. Now notify the GAIA administrators that your installation is ready and they will update the master copy of the database so that GAIA can direct users to your data.

Taking your node offline

If your GAIA node will be unavailable for a prolonged period (eg several days) please notify the GAIA administrators so that your node can be designated offline in the master copy of the database.

Software updates

Use subversion to update the installed software to the latest version. Assuming you installed into /var/www/gaia:

svn update /var/www/gaia/svn

On some occasions it may be necessary to update the configuration files to include new values; the appropriate details will be emailed to the node maintainers if it is necessary. For this reason we advise against placing the svn update command inside a cron job.

It is good practice to update your local copy of the GAIA database before running svn update as some software upgrades rely on additions to the database.