An Anno-J 'instance' is a website that you can visit to use the application. For example, the Salk Epigenome site is an 'instance'. Using an instance of Anno-J is simple; just visit the website using a W3C compliant web browser such as Safari or Firefox.
Creating an instance is a little more involved and requires website administration skills plus access to a web server (Mac OS X users: you already have access to the Apache web server). If you don't feel confident at this stage, then contact your local website administrator for advice.
If you have no intention of connecting to remote data sources then you do not need to read any further
Unfortunately, connecting to remotely hosted data is not as easy as it should be. This is due to the same origin policy, a security mechanism implemented in modern web browsers that prevents cross-domain requests (with the exception of reference to cross-domain assets such as stylesheets, images and javascripts). Various work-arounds exist, such as URL rewriting, Flash HTTPRequest, dymanic <script> tag generation, and SubSpace, but these either introduce new security vulnerabilities or are not suitable for high volume data transmission.
We can expect to see browsers supporting cross-domain XHR in the next few years. In the meantime, the only truly safe way to enable cross-domain requests is with a properly configured reverse proxy. If you are not familiar with configuring your web-server, then you should probably handball this job to a system administrator at this point, as an overly permissive reverse proxy may be abused.
In short, a reverse proxy is a server that receives a request to visit a remote site from some client, carries out the request on the client's behalf and then returns the result to the client as if it came from the server itself. This resolves same-origin issues as the browser sees all data as coming from the same host as that which hosts the Anno-J instance. The catch is that remote URLs must be embedded within URLs sent to the Anno-J host and extracted by the server, requiring the ability to rewrite URLs on the server-side.
Examples of how to do this are provided for Apache 1 and 2. Consult your web-server documentation for other servers and feel free to contact me with an example of your configuration for other servers so that I may add your instructions to the list below.
The following is a sample .htaccess file for Apache 1.3. It should be placed in the same directory as your Anno-J instance HTML file and AllowOverride should be enabled in your main httpd.conf. In addition, mod_rewrite should be available, and ProxyRequests should be set to Off (as a forward proxy is not needed). After making changes to the httpd.conf, remember to restart the web-server.
### # Sample .htaccess file for Apache 1.3 # EXAMPLE ONLY, use at your own risk # Ensure that AllowOverride is enabled in the httpd.conf # Ensure that mod_rewrite is enabled and functional # Ensure that ProxyRequests are Off ### # Restrict access if you wish. A good idea when testing. Order Deny,Allow Deny from All Allow from localhost Allow from enter.your.ip.address Allow from enter.your.domain.* # For this to work, mod_rewrite must be enabled in your httpd.conf RewriteEngine On RewriteBase / # Any number of rewrite rules may be added, typically one per remote service is the most secure RewriteRule ^index\.html/(http://remote\.site1\.com/fetchers/models\.php)$ $1 [P,L] RewriteRule ^index\.html/(http://remote\.site1\.com/fetchers/reads\.php)$ $1 [P,L] RewriteRule ^index\.html/(http://remote\.site2\.com/fetchers/blah\.php)$ $1 [P,L] # Do NOT use overly permissive rules like this, you're asking for trouble if you do. # RewriteRule ^index\.html/(.*)$ $1 [P,L]
To enable reverse proxying in Apache2, use a2enmod to enable mod_proxy, mod_proxy_http and mod_rewrite (you can see a list of currently enabled modules with a2enmod -l ). In your httpd.conf ensure that ProxyRequests are Off (as a forward proxy is not required) and that AllowOverride is enabled for the Anno-J instance's directory. After you have finished altering the httpd.conf file, restart the server (/etc/inid.d/apache2 restart). Now create the .htaccess file, noting a few changes to the rewrite strategy.
### # Sample .htaccess file for Apache 2 # EXAMPLE ONLY, use at your own risk # Ensure that AllowOverride is enabled in the httpd.conf # Ensure that mod_rewrite is enabled and functional # Ensure that ProxyRequests are Off ### # Restrict access if you wish. A good idea when testing. Order Deny,Allow Deny from All Allow from localhost Allow from enter.your.ip.address Allow from enter.your.domain.* # For this to work, mod_rewrite must be enabled in your httpd.conf RewriteEngine On RewriteBase / # Any number of rewrite rules may be added, typically one per remote service is the most secure # Whatever URL you use should match what you put in your AJ config file. The more specific the better # Note: Apache2 collapses //// to / hence we need a little change to make the embedded URL trick work RewriteRule ^index\.html/http:/(remote\.site1\.com/fetchers/models\.php)$ http://$1 [P,L] RewriteRule ^index\.html/http:/(remote\.site1\.com/fetchers/reads\.php)$ http://$1 [P,L] RewriteRule ^index\.html/http:/(remote\.site2\.com/fetchers/blah\.php)$ http://$1 [P,L] # Do NOT use overly permissive rules like this, you're asking for trouble if you do. # RewriteRule ^index\.html/http:/(.*)$ http://$1 [P,L]
If you know how to achieve the above for other web-servers, please contact me with instructions and I will add them to this page.