AmiGO 2 Manual: Installation (2.3.x): Difference between revisions
m (Sjcarbon moved page AmiGO 2 Manual: Installation to AmiGO 2 Manual: Installation (2.3.x): Need more granularity.) |
|||
(23 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
=Preliminaries= | |||
The current released production version is 2.3.x (pending). | |||
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. | |||
While the correct version of OWLTools is now included as a JAR with the AmiGO installation, but the [[GOlr]] documentation is still available separately and should be read for proper GOlr/Solr installation. | |||
Handling permissions and the like for the various servers are not explicitly covered in this document, but I'd like to make the observation that the AmiGO 2 and client stuff can be handled as any user as long as they have read write permissions to a htdocs and cgi-bin directory in a properly configured Apache 2 installation and the Solr server is locally accessible. Similarly, most CGI servers should be able to deliver AmiGO. | |||
==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 xvfb python-virtualenv g++ node | |||
You will need to also get some semi-modern form of Node.js (node and npm) onto your system. AmiGO currently requires 0.10+, with 0.12+ recommended. Options that have worked for us are ppa:chris-lea/node.js and the | |||
online installer: https://nodejs.org/en/download/package-manager/#debian-and-ubuntu-based-linux-distributions (recommended, although we haven't tried 4+ yet). | |||
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 | |||
== | ==Configuring the Web Server== | ||
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. | 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: | Prepare the amigo web directories: | ||
Line 67: | Line 91: | ||
(amigo) | (amigo) | ||
sudo service apache2 reload | sudo service apache2 reload | ||
=AmiGO 2: Client software installation= | =AmiGO 2: Client software installation= | ||
Line 91: | Line 96: | ||
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''. | 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== | ==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'''. | 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. | 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== | ==AmiGO 2== | ||
Line 107: | Line 108: | ||
mkdir -p ~/local/src/git | mkdir -p ~/local/src/git | ||
cd ~/local/src/git | cd ~/local/src/git | ||
git clone git://github.com/ | git clone git://github.com/geneontology/amigo.git | ||
cd amigo | cd amigo | ||
git checkout 2.3.x | |||
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: | 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: | ||
npm install | |||
Now, possibly using one of the example configurations (conf/examples/*.yaml), make sure that you have a usable conf/amigo.yaml. | |||
./node_modules/.bin/gulp install | |||
This command will need to be re-run every time ther eis a modification to the configuration. | |||
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 | |||
An example configuration can be found here: https://github.com/geneontology/amigo/blob/master/conf/examples/amigo.yaml.tomodachi | |||
=Afterwards= | =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 gulpfile.js== | |||
For some time now, all day-to-day development, handling, distribution, and loading of [[AmiGO_2]] and [[GOlr]] have been handled with gulpfile.js. 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 gulpfile.js not yet fully documented (real soon now), it may be worth perusing. This is issue: https://github.com/kltm/amigo/issues/26 | |||
[[Category:AmiGO_2_Manual]] | [[Category:AmiGO_2_Manual]] | ||
[[Category:AmiGO_2]] | [[Category:AmiGO_2]] | ||
[[Category:Software]] | [[Category:Software]] |
Latest revision as of 19:35, 8 August 2016
Preliminaries
The current released production version is 2.3.x (pending).
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.
While the correct version of OWLTools is now included as a JAR with the AmiGO installation, but the GOlr documentation is still available separately and should be read for proper GOlr/Solr installation.
Handling permissions and the like for the various servers are not explicitly covered in this document, but I'd like to make the observation that the AmiGO 2 and client stuff can be handled as any user as long as they have read write permissions to a htdocs and cgi-bin directory in a properly configured Apache 2 installation and the Solr server is locally accessible. Similarly, most CGI servers should be able to deliver AmiGO.
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 xvfb python-virtualenv g++ node
You will need to also get some semi-modern form of Node.js (node and npm) onto your system. AmiGO currently requires 0.10+, with 0.12+ recommended. Options that have worked for us are ppa:chris-lea/node.js and the online installer: https://nodejs.org/en/download/package-manager/#debian-and-ubuntu-based-linux-distributions (recommended, although we haven't tried 4+ yet).
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
Configuring the Web Server
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
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/geneontology/amigo.git cd amigo git checkout 2.3.x
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:
npm install
Now, possibly using one of the example configurations (conf/examples/*.yaml), make sure that you have a usable conf/amigo.yaml.
./node_modules/.bin/gulp install
This command will need to be re-run every time ther eis a modification to the configuration.
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
An example configuration can be found here: https://github.com/geneontology/amigo/blob/master/conf/examples/amigo.yaml.tomodachi
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 gulpfile.js
For some time now, all day-to-day development, handling, distribution, and loading of AmiGO_2 and GOlr have been handled with gulpfile.js. 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 gulpfile.js not yet fully documented (real soon now), it may be worth perusing. This is issue: https://github.com/kltm/amigo/issues/26