Installing VSO

Due to some concerns from the legal folks regarding distribution of software, the instructions are intentionally missing a key variable -- the location of the 'DarkPAN' site that you need to pull the software from. Please contact [people/JoeHourcle Joe Hourclé] if you're interested (and so we can get feedback to improve these instructions).

VSO Install Script

First, download the shell script that'll do 90% (ish) of the work:

wget http://sdac.virtualsolar.org/Installers/install_vso.sh

or

curl -O http://sdac.virtualsolar.org/Installers/install_vso.sh

If you don't have curl or wget installed ... that's a problem, as you'll need something to fetch the dependancies and such.

Modify the file as appropriate so it'll install where you want, and knows about the super-secret place where the VSO perl scripts are. I'd also recommend that you look over what the script's doing, as it's generally a bad idea to just download stuff from the internet and run it. (also, it's going to download other scripts part way through and run it under sudo to set up all of the local configuration bits ... set PAUSE_AFTER_DOWNLOAD to get it to wait for you to inspect 'em first. You can also set SUDO to blank, to force the scripts to run as the current user)

Potential Problems

If you're running a newer version of perl, but the installer finds older libraries first, it might give you a message like :

Module::CoreList 2.80 (loaded from (somewhere)/lib/Module/CoreList.pm) doesn't
seem to have entries for perl 5.016003. You're strongly recommended to upgrade
Module::CoreList from CPAN.

Although it *looks* like a warning, it's actually an error that will keep cpanm from installing. You'll need to fix your library paths or update Module::CoreList either manually or using cpan (not cpanm) before you can continue.

For newer versions of CentOS, we've had problems where the install script complains about missing Perl modules that are already installed :

! Installing the dependencies failed: Module 'Test::More' is not installed
! Bailing out the installation for Scalar-List-Utils-1.45.
! Installing the dependencies failed: Module 'Carp' is not installed
! Bailing out the installation for Exporter-5.72.
! Installing the dependencies failed: Module 'Exporter' is not installed, Module 'Test::More' is not installed
! Bailing out the installation for Carp-1.38.

Because we use the -L flag to cpanm, it tries to keep an isolated copy of the installed libraries ... but something about the configuration of CentOS with perl installed from yum has these modules not flagged as 'core' and thus exempt from the isolation. You'll need to install the modules that it complains about using -l and possibly --force if it claims it's already installed:

$ cpanm -l /opt/vso --force Test::More ExtUtils::MakeMaker Carp Exporter Scalar::List::Utils

You might also get a message complaining about after you've entered a bunch of configuration parameters, but it complains:

Can't locate Physics/Solar/VSO/Config.pm in @INC (@INC contains: blib/arch blib/lib /usr/local/lib64/perl5 /usr/local/share/perl5 /usr/lib64/perl5/vendor_perl /usr/share/perl5/vendor_perl /usr/lib64/perl5 /usr/share/perl5 .) at Config.PL line 3.
BEGIN failed--compilation aborted at Config.PL line 3.

We can force a fix by going into the module it was trying to build, and telling the Config.PL script where the VSO modules are installed:

cd ~/.cpanm/latest-build/Physics-Solar-VSO-(something)
vi Config.PL
# add at the top: use lib '/opt/vso/lib/perl5';
# then save & exit
cpanm .

install the CGIs and static files

Once the scripts have finished running, you should get a message similar to:

To finish the install:

   copy files in /tmp/cgi to the local path for http://servername.example.com/cgi-bin/vso
  
   copy files in /opt/vso/html to the local path for http://servername.example.com/vso

We'll assume for this example that the webserver root is /var/www/html and the CGI root is /var/www/cgi-bin

You have a few options for the static files:

1. Symlink the directories

   ln -s /opt/vso/html /var/www/html/vso 

The only advantage is that you won't have to do anything in the future after updates. Many web servers don't allow symlinks (and it's a good idea not to), so you may get reports in your webserver's error log such as:

Symbolic link not allowed or link target not accessible: /var/www/html/vso

2. Set up an Alias in the httpd.conf file or the appropriate site/*.conf file for that virtual host:

    Alias /vso/ /opt/vso/html

You will need to restart your webserver ( issue the command apachectl graceful ).

This might not work if you followed the CIS benchmarks to the letter (not allowing access to files outside of the web root)

3. Or, just copy the files into place:

cp -r /opt/vso/html /var/www/html/vso

..

for the CGIs, you really want to copy them into place. Barring any errors, they'll have been copied into /tmp/cgi with the appropriate names to use.

cp -r /tmp/cgi /var/www/cgi-bin/vso

(note to self -- they don't check to see if you over rode the filenames when configuring; they assume the default names)

Modify the Web UI configuration (if appropriate)

This is only necessary if you're running the 'UI' (web front end) portions of the VSO. If you're only running the APIs, this isn't necessary.

edit : /opt/vso/etc/webui_config.xml

add a '<server>' block to describe the instance. You'll want to use whatever you set for INSTANCE_ID as the 'name' The version number doesn't really matter.

then look for the <version> block ... change it so that only your instance ID is listed in there as a '<current>' element. (or add it in, and it'll round-robin)'

Outstanding issues (TODO)

• automatically generate a WSDL file, when appropriate
• add all of the mod_perl scripts to the various installers (and fix PrepareCGIs.PL to know about 'em)
• break webui_config.xml into a local & global part, so we can automatically update w/out overriding changes
• automatically modify webui_config.xml
• create something to set up the environment after the fact so you can easily update individual modules.
• have PrepareCGIs script get saved to /opt/vso/bin (with wrapper around it so it'll run clean, or rework logic so it moves it to /tmp, then modifies, so doesn't need elevated privs)