AmiGO 2 Manual: Installation (2.4.x): Difference between revisions
Line 53: | Line 53: | ||
* we are using a random local IP address for testing--you will have to change that | * we are using a random local IP address for testing--you will have to change that | ||
* for the time being we're using a remote GOlr server--again you'll want to setup your own and change this | * for the time being we're using a remote GOlr server--again you'll want to setup your own and change this | ||
--- | --- | ||
AMIGO_1X_PUBLIC_CGI_BASE_URL: | AMIGO_1X_PUBLIC_CGI_BASE_URL: | ||
Line 67: | Line 67: | ||
type: boolean | type: boolean | ||
value: 1 | value: 1 | ||
AMIGO_CGI_BASE_URL: | |||
comment: Please enter the URL that this path (plus the AMIGO_PROJECT_NAME) maps to. | |||
type: url | |||
value: http://localhost/cgi-bin/amigo2 | |||
AMIGO_CGI_PARTIAL_PATH: | |||
comment: Please enter the full path to a usable CGI enabled directory. AMIGO_PROJECT_NAME will be used as a new directory name in this directory. | |||
type: directory | |||
value: /srv/www/cgi-bin | |||
AMIGO_CONFIGURED: | |||
comment: "This variable must be edited (to 1) before installing AmiGO.\n" | |||
type: boolean | |||
value: 0 | |||
AMIGO_DYNAMIC_PATH: | AMIGO_DYNAMIC_PATH: | ||
comment: The full path to the location of the perl binaries. | comment: The full path to the location of the perl binaries. | ||
Line 79: | Line 91: | ||
type: string | type: string | ||
value: '' | value: '' | ||
AMIGO_HTDOCS_BASE_URL: | |||
comment: Please enter the URL that this path (plus the AMIGO_PROJECT_NAME) maps to. | |||
type: url | |||
value: http://localhost/amigo2 | |||
AMIGO_HTDOCS_PARTIAL_PATH: | |||
comment: Please enter the full path to a usable static document directory. AMIGO_PROJECT_NAME will be used as a new directory name in this directory. | |||
type: directory | |||
value: /srv/www/htdocs | |||
AMIGO_LAYOUT_SEARCH: | AMIGO_LAYOUT_SEARCH: | ||
comment: A whitespace separated list of class IDs to use for live search tabs on the search page. | comment: A whitespace separated list of class IDs to use for live search tabs on the search page. | ||
type: string | type: string | ||
value: annotation ontology bioentity | value: annotation ontology bioentity complex_annotation family general bbop_term_ac | ||
AMIGO_PROJECT_NAME: | |||
comment: Please enter the name of this AmiGO installation. | |||
type: string | |||
value: amigo2 | |||
AMIGO_PUBLIC_CGI_BASE_URL: | |||
comment: Please enter the partial public URL. | |||
type: true | |||
value: http://amigo.geneontology.org/cgi-bin/amigo | |||
AMIGO_PUBLIC_GALAXY_URL: | |||
comment: Please enter the public URL of the Galaxy server. | |||
type: url | |||
value: http://galaxy.berkeleybop.org/ | |||
AMIGO_PUBLIC_GOLR_URL: | AMIGO_PUBLIC_GOLR_URL: | ||
comment: The public URL of the GOlr server (including slash). | comment: The public URL of the GOlr server (including slash). | ||
type: url | type: url | ||
value: http://localhost:8080/solr/ | value: http://localhost:8080/solr/ | ||
AMIGO_PUBLIC_OPENSEARCH_URL: | |||
comment: Please enter the public URL of the GO-defined OpenSearch server. | |||
type: url | |||
value: '' | |||
AMIGO_ROOT: | AMIGO_ROOT: | ||
comment: 'Unless you are doing something strange, the parent directory of this file.' | comment: 'Unless you are doing something strange, the parent directory of this file.' | ||
type: directory | type: directory | ||
value: /home/sjcarbon/local/src/git/amigo | value: /home/sjcarbon/local/src/git/amigo | ||
AMIGO_SEARCH_DEFAULT: | |||
comment: The default search personality to use. | |||
type: string | |||
value: annotation | |||
AMIGO_SERVER_NAME: | AMIGO_SERVER_NAME: | ||
comment: 'The name by which your AmiGO instance wishes to known--think load balancer or cache situations. If you would rather this information not be reported, leave blank.' | comment: 'The name by which your AmiGO instance wishes to known--think load balancer or cache situations. If you would rather this information not be reported, leave blank.' | ||
Line 128: | Line 168: | ||
value: /home/sjcarbon/local/src/git/amigo/metadata | value: /home/sjcarbon/local/src/git/amigo/metadata | ||
If everything is correct, installing AmiGO 2 should be as simple as: | If everything is correct, installing AmiGO 2 should be as simple as: | ||
Revision as of 16:53, 15 September 2014
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 make rsync rhino libconfig-yaml-perl liburi-perl libjson-xs-perl libossp-uuid-perl libfile-type-perl libfreezethaw-perl libwww-mechanize-perl libcgi-application-perl libdbi-perl libdata-formvalidator-perl libcgi-application-plugin-session-perl libcgi-application-plugin-tt-perl libgraph-perl libclone-perl libxml-xpath-perl libdbd-sqlite3-perl git yui-compressor naturaldocs libgraphviz-perl libfile-type-perl libfile-slurp-perl libdbd-mysql-perl kwalify libxml-libxml-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 install script would do this automatically for us while throwing an error, but we'll just do it directly like:
make initialize
This step only ever needs to be performed once, from now on you will just modify the conf/amigo.yaml file.
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
- for the time being we're using a remote GOlr server--again you'll want to setup your own and change this
--- AMIGO_1X_PUBLIC_CGI_BASE_URL: comment: The public URL of an available AmiGO 1.x instance for link references. type: url value: http://amigo1.geneontology.org/cgi-bin/amigo AMIGO_BALANCER: comment: 'Mark this AmiGO 2 installation as behind a load balanacer or similar system. The practical effect of this flag is that if AmiGO detects *.error files (usually created by the global-message.pl script), it will return a 503 page signalling any upstream system that the instance is not currently ready.' type: boolean value: 0 AMIGO_BETA: comment: Mark the AmiGO site as BETA (triggers some changes in variables and installed features). type: boolean value: 1 AMIGO_CGI_BASE_URL: comment: Please enter the URL that this path (plus the AMIGO_PROJECT_NAME) maps to. type: url value: http://localhost/cgi-bin/amigo2 AMIGO_CGI_PARTIAL_PATH: comment: Please enter the full path to a usable CGI enabled directory. AMIGO_PROJECT_NAME will be used as a new directory name in this directory. type: directory value: /srv/www/cgi-bin AMIGO_CONFIGURED: comment: "This variable must be edited (to 1) before installing AmiGO.\n" type: boolean value: 0 AMIGO_DYNAMIC_PATH: comment: The full path to the location of the perl binaries. type: directory value: /home/sjcarbon/local/src/git/amigo/perl/bin AMIGO_DYNAMIC_URL: comment: The URL that AMIGO_DYNAMIC_PATH maps to. type: url value: http://localhost:9999 AMIGO_GOOGLE_ANALYTICS_ID: comment: Google analytics ID. Optional. type: string value: AMIGO_HTDOCS_BASE_URL: comment: Please enter the URL that this path (plus the AMIGO_PROJECT_NAME) maps to. type: url value: http://localhost/amigo2 AMIGO_HTDOCS_PARTIAL_PATH: comment: Please enter the full path to a usable static document directory. AMIGO_PROJECT_NAME will be used as a new directory name in this directory. type: directory value: /srv/www/htdocs AMIGO_LAYOUT_SEARCH: comment: A whitespace separated list of class IDs to use for live search tabs on the search page. type: string value: annotation ontology bioentity complex_annotation family general bbop_term_ac AMIGO_PROJECT_NAME: comment: Please enter the name of this AmiGO installation. type: string value: amigo2 AMIGO_PUBLIC_CGI_BASE_URL: comment: Please enter the partial public URL. type: true value: http://amigo.geneontology.org/cgi-bin/amigo AMIGO_PUBLIC_GALAXY_URL: comment: Please enter the public URL of the Galaxy server. type: url value: http://galaxy.berkeleybop.org/ AMIGO_PUBLIC_GOLR_URL: comment: The public URL of the GOlr server (including slash). type: url value: http://localhost:8080/solr/ AMIGO_PUBLIC_OPENSEARCH_URL: comment: Please enter the public URL of the GO-defined OpenSearch server. type: url value: AMIGO_ROOT: comment: 'Unless you are doing something strange, the parent directory of this file.' type: directory value: /home/sjcarbon/local/src/git/amigo AMIGO_SEARCH_DEFAULT: comment: The default search personality to use. type: string value: annotation AMIGO_SERVER_NAME: comment: 'The name by which your AmiGO instance wishes to known--think load balancer or cache situations. If you would rather this information not be reported, leave blank.' type: string value: localhost AMIGO_STATIC_PATH: comment: The full path to a usable static document directory where static and staging are located. type: directory value: /home/sjcarbon/local/src/git/amigo/static AMIGO_STATIC_URL: comment: The URL for the static content. Can be local or remote. type: url value: http://localhost:9999/static AMIGO_TERM_REGEXP: comment: The regular expressions to identify internal ontology ids. type: string value: 'all|GO:[0-9]{7}' AMIGO_VERBOSE: comment: Log verbose AmiGO debugging messages. type: boolean value: 1 AMIGO_WORKING_PATH: comment: Please enter the full path to readable/writable directory that will be used for things like temporary files and logs (if enabled). type: directory value: /tmp GOLR_TIMESTAMP_LOCATION: comment: 'This is the full path to the timestamp file that is optionally produced by OWLTools during GOlr loading. It contains information about download attempt times for the different loaded files. If not found or unusable, AmiGO 2 will gracefully ignore it.' type: file value: /home/sjcarbon/local/src/git/amigo/golr_timestamp.log GO_BBOPJS_LOCATION: comment: 'If this is not redefined to a new location (e.g. the BBOP-JS staging/ directory, it will use the bbop.js bundle packaged with AmiGO 2 (the one used in the unit tests) in the external/ directory.' type: file value: /home/sjcarbon/local/src/git/amigo/external/bbop.js GO_YAML_LOCATION: comment: 'The full path to the YAML config files directory. In that directory, all files like *config.yaml will be scanned for use.' type: directory value: /home/sjcarbon/local/src/git/amigo/metadata
If everything is correct, installing AmiGO 2 should be as simple as:
make install
Configuring the Web Server (optional for non-production)
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.