AmiGO 2 Manual: Installation (2.4.x)

From GO Wiki
Jump to navigation Jump to search

Preliminaries

These instructions are intended to illustrate how to install the AmiGO 2 client software on a Ubuntu 14.04 LTS. With careful reading, these instructions should be generalizable to other cases. The installation of this client software only covers AmiGO 2 and some Apache 2 configuration.

For information on the data server that AmiGO 2 uses (covering the installation of and loading using the server software: GOlr schema for Solr, OWLTools, etc.), please see the Installation section of the GOlr documentation.

Handling permissions and the like for the various servers is not explicitly covered in this document, but I'd like to make the observation that AmiGO 2 and client stuff can be handled as any user except for the necessary Apache 2 installation (when not using dev deployment directly) and the Solr/GOlr.

Packages

Also, in addition to anything that you might need for BBOP JS (in the optional case that you are going to develop with it), the following packages are needed:

sudo apt-get -u install git make rhino kwalify yui-compressor naturaldocs libcgi-application-perl libcgi-application-plugin-session-perl libcgi-application-plugin-tt-perl libclone-perl libconfig-yaml-perl libdbi-perl libdbd-sqlite3-perl libdbd-mysql-perl libdata-formvalidator-perl libossp-uuid-perl libfile-type-perl libfile-slurp-perl libfreezethaw-perl libgraph-perl libgraphviz-perl libjson-xs-perl liburi-perl libwww-mechanize-perl libxml-libxml-perl libxml-xpath-perl

The package libsql-tokenizer-perl is also required (by GOOSE for query checking), but may no longer be available in repositories. If you're interested in using a locally configured GOOSE, you may need to manually install this package along the lines of:

sudo apt-get -u install dh-make-perl
cd /tmp
dh-make-perl --build --cpan SQL::Tokenizer
sudo dpkg -i libsql-tokenizer-perl_???_all.deb

Depending on what you're doing with CPAN in this case, you may also need to install a helper library first:

sudo apt-get -u install liblocal-lib-perl

AmiGO 2: Client software installation

The AmiGO 2 client software can be used completely separately from the server software as long as a Solr server with a compliant schema is available somewhere.

BBOP JS: Not Usually Needed

AmiGO 2 no longer depends on an additional download of BBOP JS, it now will use the bundled copy by default. Most users can skip the next paragraph.

For widget developers, since most of the JavaScript in AmiGO 2 relies on this library, the first step in installing AmiGO 2 is to get BBOP JS somehow available. While AmiGO 2 repository (below) comes with a packaged version of bbop.js in the _data/ directory (which is also the default when installing AmiGO 2), if you're interested in hacking around BBOP JS in conjunction with AmiGO 2, you'll have to build it yourself and change the BBOP_JS variable in the Makefile to the appropriate location so you can use the "make refresh" command. Since we don't want to repeat ourselves here, full downloading and building instructions can be found on its homepage at https://github.com/kltm/bbop-js . Scroll down a bit to "Local (building)" to get to the pertinent information.

AmiGO 2

This software contains the GO-specific things that BBOP JS does not support--the client (web server) code for AmiGO 2. For the sake of convenience (and using a similar directory layout to the developers), we'll get it like:

mkdir -p ~/local/src/git
cd ~/local/src/git
git clone git://github.com/kltm/amigo.git
cd amigo

Next, we have to configure the AmiGO 2 installation given what we have with our BBOP JS and Apache 2 installations. The file to edit is:

conf/amigo.yaml

If you do not have a conf/amigo.yaml file, you can start from the default template with:

cp conf/.initial_values.yaml conf/amigo.yaml

The most important (and fiddly) part of installing AmiGO 2 is this configuration file. For our case, in a local testing environment, the resulting amigo.yaml might look like the following. Please note that:

  • variables names have occasionally been changed, so this might not be exactly like your output
  • we are using a random local IP address for testing--you will have to change that
  • we are using the username foo
  • for the time being we're using a remote GOlr server--again you'll want to setup your own and change this
TODO

If everything is correct, installing a dev instance AmiGO 2 should be as simple as:

make install

This will create configuration and amigo2 JavasScript packages, as well as run unit tests and create API docs.

Configuring the Web Server

Development (local)

To run the local embedded development server, you will have to add the following package:

sudo apt-get -u install libcgi-application-server-perl

Running should now be as simple as a:

make run

The dev server should now be running on port :9999 (given the amigo.yaml above).

Production (Apache 2)

While we are not officially supporting any particular web server or configuration, we make available here some notes about setting up a server on a new installation.

AmiGO 2 was developed with Apache 2 (see preliminaries above for instructions), but I'd suspect that any CGI-capable web server would be sufficient. Configuring and running a web server is outside the scope of this document.

Prepare the amigo web directories:

sudo mkdir -p /srv/www-amigo
sudo chown amigo /srv/www-amigo
sudo chgrp amigo /srv/www-amigo
mkdir /srv/www-amigo/cgi-bin
mkdir /srv/www-amigo/htdocs

The minimal configuration we're using is:

<VirtualHost *:80>
 ServerAdmin webmaster@localhost

 DocumentRoot /srv/www-amigo/htdocs
 <Directory />
  Options FollowSymLinks
  AllowOverride None
 </Directory>
 <Directory /srv/www-amigo/htdocs/>
  Options Indexes FollowSymLinks MultiViews
  AllowOverride None
  Order allow,deny
  allow from all
 </Directory>

 ScriptAlias /cgi-bin/ /srv/www-amigo/cgi-bin/
 <Directory "/srv/www-amigo/cgi-bin">
  AllowOverride None
  Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
  Order allow,deny
  Allow from all
 </Directory>

 ErrorLog ${APACHE_LOG_DIR}/amigo-error.log

 # Possible values include: debug, info, notice, warn, error, crit,
 # alert, emerg.
 LogLevel warn

 CustomLog ${APACHE_LOG_DIR}/amigo-access.log combined

</VirtualHost>

Install Apache:

sudo apt-get -u install apache2
sudo a2dissite
(default)
sudo emacs -nw /etc/apache2/sites-available/amigo
sudo touch /var/log/apache2/amigo-error.log
sudo touch /var/log/apache2/amigo-access.log
sudo chgrp adm /var/log/apache2/amigo-*.log
sudo chmod 640 /var/log/apache2/amigo-*.log
sudo a2ensite
(amigo)
sudo service apache2 reload

Afterwards

System scripts

You may want to check out various AmiGO 2 system scripts referred to in the message at the end of the installation process: global-message.pl, clean-filesystem.pl, and blank-kvetch.pl. More information can be found in AmiGO_2_Manual:_Administration.

All Glory to the Makefile

For some time now, all day-to-day development, handling, distribution, and loading of AmiGO_2 and GOlr have been handled with the Makefiles in amigo/Makefile and amigo/golr/Makefile respectively. If it cannot be done by changing your environment variables and rerunning the target that you want, you might want to reconsider what you're doing.

While the Makefiles are not yet fully documented (will add them to our NaturalDocs real soon now), they may be worth perusing. This is issue: https://github.com/kltm/amigo/issues/26

Images

A KVM image of Ubuntu 12.04.2 of the above configuration (created 2013-07-24) for the AmiGO 2 fronted (only) is available at "http://api.berkeleybop.org/images/"; the name of the image is "a2.img". Just paste those together (I don't want to have the direct link here). The md5sum is 6d60b045fc38fdd8d98222367a506c51.

  • it is an 8GB image, which should have no non-AmiGO 2 services or software
  • hostname: amigo
  • core username: amigo
  • pass: ogima
  • in conf/amigo.yaml, the wired the address is 192.168.122.213 for testing--you'll need to change that
  • the GOlr server is the current public one--you'll need to create your own backend and change it
  • ServerName is not set for Apache.