Building Backstage
Working with Backstage is not as simple as working with Exhibit Scripted. In addition to HTML and publishing web pages, Backstage is Java software that acts as a server. If you are not familiar with Java development, this may not be the project for you to start learning on; consider getting some help.
You will need all of the following installed on your development system.
Get the source;
$ mkdir ~/e3src && cd ~/e3src
$ git clone git://github.com/zepheira/babel.git
$ git clone git://github.com/zepheira/backstage.git
$ git clone git://github.com/zepheira/exhibit3.git
$ svn checkout http://simile-butterfly.googlecode.com/svn/trunk/ butterfly
Build;
$ cd babel && mvn install
$ cd ../butterfly && mvn install && ant build
$ cd ../exhibit3/scripted && ant dist
$ cd ../../backstage && mvn package
Note; if you're building this with Java 7 and have problems with Butterfly, consult this issue
Connect the Exhibit3 scripts to the Web server;
$ cd ../backstage && ln -s ~/e3src/exhibit3/scripted/dist modules/exhibit/api
The startup script exists at ~/e3src/backstage/backstage and contains several configuration settings.
- MXMEM specifies the maximum Java heap size. The "correct" value here depends on several factors including the number and size of datasets, the number of facets in the hosted exhibits, the choice of disk or memory based database, as well as uniqueness qualities and size of the faceted properties. Start with the default setting of 1024M and increase it as required, when you run into a Java OutOfMemoryError. NOTE: for the Backstage demos, we observed that each new 100K item dataset and 2 facet exhibit using a memory based database, required an additional 1.5G of heap.
- set HOST and PORT to your publicly accessible host and port information. Backstage uses this information to determine your mount point (which can be overridden using the SERVER_ROOT variable) which is in turn used as the base URL for any uploaded datasets.
- set DATABASE_DIR to the directory where the databases corresponding to the uploaded datasets are to be stored. A non-absolute path is interpreted relative to the Butterfly home, and the default is simply "databases" (or ~/e3src/butterfly/databases)
Backstage is developed as a Butterfly application and deployed in a Jetty servlet container which can be configured via its "web.xml" file, ~/e3src/butterfly/main/webapp/WEB-INF/web.xml.
One setting of interest for Backstage is the session timeout, as the lifetime of a Backstage session, which contains in-memory database, is also determined by this value. If the data export feature isn't used, the in-memory database is removed from memory after the session times-out.
The following addition to web-app root of the web.xml document specifies a session timeout of 1440 minutes (1 day);
<session-config>
<session-timeout>1440</session-timeout>
</session-config>
Once configured, run;
$ ./backstage