Simple Danno / Dannotate Installation Instructions
This page will describe the simple (yet to be written) tool that takes one of the pre-built Danno / Dannotate WAR files and interactively modifies some of the simple configuration properties to suit local conditions.
For now, the following procedures will get the demo version of Danno and Dannotate running.
These instructions assume the following:
- You are installing the Danno/Dannotate demo on a Linux / Unix machine. (We recommend using Linux or Unix as your server platform. There's no reason to think that Windows or MacOS won't work, but these instructions don't cover installation on those platforms.)
- You have root access on the machine, you are familiar with Linux / Unix system administration and security, and you are familiar with any relevant local policies about installing software.
- Port 80 is not currently in use on your machine. (If it is, or if you want Danno / Dannotate to run on a different port number, you will need to customize the WAR file and/or setup a reverse proxy on the existing port 80 server.)
- It is OK to use "localhost" as the domain name for the Danno / Dannotate services. This will make it impossible to access to the demo services from another machine. (If you want to enable access from other machines, you will need to customize the WAR file.)
Here is what you need to do:
- Check that your machine has a recent version of Java 6.0 installed. As a first step, run the command from the command line.
If this reports the version as "java_1_6_0_xx", you have Java 6.0 installed and on your search path. If it reports some other version, or if the "java" command is not found, you may need to download and install it.
Java 6.0 can be downloaded from the Sun Java website, or using your system's package manager.
- If you download from the Sun server, make sure that you select a J2SE 6.0 SDK (not a JRE) distribution.
- If you use your package manager, the package you most likely need will labeled "openJDK" and will include the "6.0" version number.
Once you have installed the Java, check that the $JAVA_HOME environment variable is set and that $JAVA_HOME/bin is on your search path.
- Check that you have a copy of Apache Tomcat 5.5 installed. Tomcat is available via your system's package manager, and if it is installed that way, there is probably a launch script in the "/etc/init.d/" directory. Alternatively, Tomcat may have been downloaded as a tarball from Apache Tomcat website, and installed somewhere.
If necessary, download and install Tomcat 5.5 (from the above site) or using your package manager. Then set the $CATALINA_HOME environment variable to the Tomcat installation directory.
- TomcatPortChange the Tomcat server configuration so that it listens on port 80 as follows:
- Open the file $CATALINA_HOME/conf/server.xml in a text editor.
- Search for a <Connector> element with 'port="80"'. If you find one, port 80 is already enabled.
- Otherwise, search for the <Connector> element with 'port="8080"'.
- Either, change "8080" to "80", or clone the entire element and change "8080" to "80" in the copy.
- Check that you can start and stop Tomcat. There are various ways to do this, but a simple procedure is as follows (assuming that Tomcat is not currently running):
- Start Tomcat by running the following command:
sudo $CATALINA_HOME/bin/startup.sh
- Use your web browser to visit "http://localhost/". You should see the Tomcat 5.5 default home page.
- Stop Tomcat by running the following command:
sudo $CATALINA_HOME/bin/shutdown.sh
- If you want to annotate external resources using your Dannotate demo service, the Page Repeater service must be able to access them. For this to be possible, Tomcat may need to be configured to use your network's local web proxy server. The easy way to do this is to launch Tomcat with arguments that set the Java system properties. Assuming that you launch Tomcat with the "startup.sh" script (see above), you can set the relevant properties in the $JAVA_OPTS environment variable as follows:
export JAVA_OPTS="-Dhttp.proxyHost=proxy.example.com \
-Dhttp.proxyPort=8080 -Dhttp.nonProxyHosts=localhost" - Create a temporary directory to hold the demo server's Sesame triplestore.
- Now install the "combined.demosite" WAR file into your Tomcat "webapps" directory, and start Tomcat.
sudo $CATALINA_HOME/bin/shutdown.sh
# NB: use 'danno.war' as the destination filename
cp combined.demosite.war $CATALINA_HOME/webapps/danno.war
sudo $CATALINA_HOME/bin/startup.sh
- Wait a few seconds for Tomcat to unpack the webapp and start the servlets. Then use your web browser to visit "http://localhost/danno/index.html". If all is well, you should see the Danno demo page. If not, take a look at the log files $CATALINA_HOME/logs/catalina.out and $CATALINA_HOME/logs/Danno.log.
- Navigate to the Dannotate demo page at "http://localhost/danno/danmnotate.html", follow the instructions for installing the bookmarklets, and then see if you can create annotations on the current page.
If you cannot figure out if Dannotate is working properly, trying visiting the Public Dannotate Demo page, and compare the behavior with your installed copy. (But note that you need to use different bookmarklets for your installation and the public one!)
Note that running Tomcat as "root" potentially places your system at risk. If a remote user was able to break Java / Tomcat / Danno security they could theoretically gain root access to your machine. But this should not be a significant concern if you are running Danno / Dannotate with the default hostname of "localhost" and not advertising the installation's existence.
The recommended way to customize the Danno / Dannotate configurations is to create your own 'custom site' project as described in the Customization page. But if that is too complicated, here is a quick and dirty way to make simple changes to the configurations.
- Following the steps of the procedure above, deploy the unmodified version of the "combined.demosite" WAR file, and start Tomcat.
- After allowing time for Tomcat to unpack the WAR file, shut down the Tomcat.
- Change directory to $CATALINA_HOME/webapps/danno/WEB-INF/
- Using a text editor, change the relevant Spring wiring files, properties files, JSPs and other stuff to implement your changes.
- Restart Tomcat, and try out your changes.
- Repeat as necessary.
As we said above, this is a quick and dirty approach, and you should not even consider using it for customizing Danno / Dannotate for use in a production site.
The following headings list some simple tweaks to the Danno / Dannotate configurations:
ChangeHostPortChanging the hostname and/or port number
The "combined.demosite" WAR file uses "localhost" and "80" as the default hostname and port number for the Danno / Dannotate services. If you want to change these (using the quick and dirty approach above), edit the .../WEB-INF/classes/substitution.properties and replace the line that says:
with the following three lines (for example):
hostname=www.example.com
danno.hostname=${hostname}:8080
dannotate.hostname=${hostname}:8080The "combined.demosite" WAR file has some rather dangerous admin APIs enabled by default. One for example allows anyone to erase the entire triple store. To disable these APIs, edit the .../WEB-INF/classes/override.properties and replace the line that says:
dannoProps.danno.webAdmin=true
with a line that says:
dannoProps.danno.webAdmin=false
The Danno configurations include a sample Spring security configuration that defines a small set of user names, passwords and roles, and restricts access to certain APIs based on the role. This file is disabled by default.
To add some simple security to your site, do the following:
- Edit .../WEB-INF/Danno-security.xml to replace the usernames and passwords there-in with real user names and passwords. Since the passwords are in clear, you should take all necessary steps to secure this file. Alternatively, consider adding a password encoder and replacing the clear passwords with hashes as described here.
- Edit .../WEB-INF/web.xml to remove the "<!--" and "-->" markers that comment out the "springSecurityFilterChain" filter and filter mapping.
Note: it is possible to replace the hard-wired authentication provider in the Danno-security.xml file with other providers; e.g. using LDAP, JAAS or one that uses a database table. Refer to the SpringSecurity documentation for more information.
It is quite possible that the machine you want to run Danno / Dannotate on is already running an Apache Httpd-based website on port 80. In this case, you will have to run your Tomcat server on a different port; e.g. 8080. You have two choices:
- The simple approach is to advertise the Danno / Dannotate services to your network (and beyond) on port 8080. For a test installation, this should be fine, but port 8080 (or indeed any non-standard port number) can be problematic due to firewall restrictions on your site or on the networks of some remote users.
- The more robust approach is to advertize the Danno / Dannotate services on port 80 (i.e. on your Apache server), and configure Apache to reverse proxy the requests to your Tomcat server on port 8080.
A vanilla Tomcat 5.5 server is configured to listen on port 8080 "out of the box". But if you (or someone else) has already reconfigured Tomcat to use a different port, you can reverse it using the procedure described here.
Assuming Tomcat 5.5 has is already configured to listen on port 8080, you simply need to change the Danno / Dannotate configurations to use port 8080 in its URLs. Do this by setting the port number as described here.
Assuming Tomcat 5.5 has is already configured to listen on port 8080, and you have an Apache service running on port 80, you now need to configure the Apache service to act as a "reverse-proxy" for Danno and Dannotate. Specifically, Apache needs to accept Danno/Dannotate requests sent on port 80 and relay them to the Tomcat server listening on port 8080. Responses similarly need to be relayed back to the original requestor.
For Apache 2.x, this is achieved using the "mod_proxy" module, as follows:
- Open the file /etc/httpd/conf/httpd.conf in a text editor. (This requires root access).
- At an appropriate point in the file add the following lines:
ProxyPreserveHost on
ProxyPass /danno/ http://localhost:8080/danno/
ProxyPassReverse /danno/ http://localhost:8080/danno/
ProxyTimeout 360
- Save the file and restart Apache by running this command:
sudo /etc/init.d/httpd restart
- Check that direct requests to port 8080 work; i.e. load "http://localhost:8080/danno/index.html" into your web browser. You should be able to access the demo pages and the various direct Danno APIs should (sort of) work. But Dannotate and the Page Repeater won't work via port 8080.
- Check that requests via port 80 work; i.e. load "http://localhost/danno/index.html" into your web browser. Danno, Dannotate and the Page Repeater should all work.
