INSTALLATION MANUAL: Mac OS X
=============================

The fci-client runs on Linux, FreeBSD, OpenBSD, Mac OS X and Windows, 
the fci-server runs on Linux, and on FreeBSD & OpenBSD using Linux emulation.

The fci-client sends data from a client to the fci-server, among which are the
output of Dick Howells qd, Operating System and Hardware information and the
most interesting files in the Folding@Home client directory.

The server does almost all processing, and uses various tools to do it.

The tools uses by the FCI server are:
- xyz2pdb
- rasmol
- convert  (from ImageMagick)
- htpasswd (from Apache)

convert and htpasswd should be installed before FCI is.

xyz2pdb is shipped with FCI, just like Dick Howells qd is. xyz2pdb is used to 
convert the current.xyz to a .pdb which is fed to rasmol.

A 32 bit Linux binary of rasmol is also shipped, but many Linux distros and
FreeBSD have native packages of rasmol. Rasmol is used to generate an image 
and/or animation of the projects in the current.xyz which the clients upload.

convert is part of ImageMagick, it's used to compile animations out of multiple 
rasmol generated images.


Installing on Mac OS X
----------------------

First install the required perl modules via MacPorts:
http://www.macports.org/

Using CPAN with the default Perl shipped in Mac OS X proved to be a pain, 
so instead MacPorts is used to get the packaged Perl modules. This does
mean another Perl environment will be installed on your Mac.

By default in: /opt/local/bin/perl.

At the time of writing Mac OS X 10.4 shipped with perl v5.8.6, 
whereas MacPorts contains perl v5.8.8.

  Perl Module           | Package     
------------------------+----------------------------------
Installer:              |                            
- XML::Simple           | p5-xml-simple         
- Getopt::Mixed         | p5-getopt-mixed       
- Date::Calc            | p5-date-calc
                        | 
Client:                 |
- LWP::UserAgent	| p5-libwww-perl
- HTTP::Request::Common | p5-libwww-perl
                        |
- Date::Calc            | p5-date-calc
- XML::Simple           | p5-xml-simple         
- Getopt::Mixed         | p5-getopt-mixed

  Perl Module           | Package     
------------------------+----------------------------------
Client:                 |                            
- system_profiler       | ?                          


Using MacPorts on Mac OS X you can install the packages in one go:

# FCI Installer only:
sudo port install p5-xml-simple p5-getopt-mixed p5-date-calc

# FCI Client only:
sudo port install p5-libwww-perl p5-date-calc p5-getopt-mixed p5-xml-simple


After the dependencies have been installed, run the installer to install the
FCI client:

# FCI client only
sudo /opt/local/bin/perl install.pl --client

The installer requires root privileges, and has several options which
you can use to customize the installation, overriding the built-in defaults:

./install.pl --help
 Folding@Home Client Info Installer v1.0
 
 Usage: install.pl [--client|--server] [OPTIONS]
 
 Options:
 -c, --client           Install the client component
 -s, --server           Install the server component
 
 -b, --bin-dir <PATH>   Path of executable files          (/usr/local/bin/)
 -o, --conf-dir <PATH>  Path of configuration files       (/usr/local/etc/fci/)
 -d, --data-dir <PATH>  Path of the data files            (/usr/local/share/fci/)
 -w, --www-dir <PATH>   Path of the website files         (/var/www/fci/)
 
 -o, --owner <NAME>     Username to own the website files (root)
 -g, --group <NAME>     Username to own the website files (www-data)
 
 -f, --force            Install files & directories even if they already exist
 -v, --verbose          Enable verbose output
 -h, --help             Print this usage information


Installing the FCI client using ./install --client comes down to the following:
 copy client/qd            -> /usr/local/bin/qd
 copy client/qdinfo.dat    -> /usr/local/share/fci/qdinfo.dat
 copy client/fci-client.pl -> /usr/local/bin/fci-client.pl

It installs the fci-client Perl script, and a copy of qd and its data file
qdinfo.dat for inital use by fci-client.pl. The FCI client will automatically
download the latest qdinfo.dat from the FCI server before every upload, it's
stored in its own per-user cache: ~/.fci/. A more recent revision of the qd
binary is only downloaded if the client is run with --update-qd. New revisions
of qd may contain bugfixes or new features you may want to have available to
your FCI client, but automatic download of the most recent qd binary from the
FCI server might overwrite a custom compiled binary in ~/.fci/, which is not
desirable.

The FCI client should now be ready to perform uploads to the server. It is
recommended to use the --verbose argument to fci-client.pl the first time the
FCI client command is tested for use. By default fci-client.pl doesn't display
any output unless it encounters an error, but the verbose output contains all
the information you need to verify its correct operation.

The fci-client.pl script needs to be scheduled to run periodically. To spread
the load on the server, it's recommended to use slightly different times for
the client uploads if there are many clients on a single server and/or the
server doesn't have many resources in terms of bandwidth, RAM or CPU power.

Add a rule like the one below to the crontab of the user who also runs the
Folding@Home client:

### crontab rule for FCI client ###
10 * * * * /opt/local/bin/perl /usr/local/bin/fci-client.pl --dir /home/folding/ --url http://example.com/fci/index.pl 
### crontab rules for FCI client ###


Troubleshooting:
................

If the fci-client.pl scripts dies with an error as the below, make sure you specify the MacPorts perl:

Can't locate Date/Calc.pm in @INC (@INC contains: /sw/lib/perl5 /sw/lib/perl5/darwin \
/System/Library/Perl/5.8.6/darwin-thread-multi-2level /System/Library/Perl/5.8.6 \
/Library/Perl/5.8.6/darwin-thread-multi-2level /Library/Perl/5.8.6 /Library/Perl \
/Network/Library/Perl/5.8.6/darwin-thread-multi-2level /Network/Library/Perl/5.8.6 \
/Network/Library/Perl /System/Library/Perl/Extras/5.8.6/darwin-thread-multi-2level \
/System/Library/Perl/Extras/5.8.6 /Library/Perl/5.8.1 .) at /usr/local/bin/fci-client.pl line 14.
BEGIN failed--compilation aborted at /usr/local/bin/fci-client.pl line 14.

This happens because fci-client.pl uses /usr/bin/perl by default which is the
system shipped perl, not the MacPorts perl which has these modules installed.

To avoid this error, don't use a command like:

/usr/local/bin/fci-client.pl --dir /home/folding/ --url http://example.com/fci/index.pl

But explicitly specify the MacPort perl binary:

/opt/local/bin/perl /usr/local/bin/fci-client.pl --dir /home/folding/ --url http://example.com/fci/index.pl