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:

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.