Warning: Can't synchronize with the repository (/var/www/svn/ambra does not appear to be a Subversion repository.). Look in the Trac log for more information.

Ambra Quickstart

Ambra is distributed as a  *.war file, which is deployed to a Tomcat container. For readers familiar with enterprise Java applications, most of this will be standard setup, except for the external dependencies on which Ambra relies:

  • A main configuration file typically stored as /etc/ambra/ambra.xml
  • Configuration for  Ehcache
  • A directory for configuration and FreeMarker templates to differentiate the journals served by a single Ambra instance.

In addition, several things are expected to be provided by the container:

  • A database connection
  • A file store service for storing/retrieving article files
  • log4j config

Setup for each of these will be covered later.

Downloading Ambra

The main line of releases, as found in our Maven repository and the  master repository branch, may contain code that is undesirably specific to PLOS. The  "generic" branch of our GitHub repository contains the latest in efforts to generify Ambra (particularly its front end) for non-PLOS users. It is strongly recommended that you check out this branch and build your own war file from it. This requires the tools Git and Maven. See "Building Ambra" below.

The war files from PLOS's main development line are available from our  Maven Repository. The latest war file resides in the directory with the highest number. Inside that directory, resides the corresponding war file. For example, if the latest release is 2.3.9, then the war file will be named: ambra-webapp-2.3.9.war

The Admin component of Ambra is also available view the  Maven Repository. These should be suitable to use with a war built from the "generic" branch. Note that the Admin version numbers will not necessarily match those of Ambra.

If you download Ambra, please let us know on one of our Mailing lists.

Building Ambra

To check out the source code:

 git clone https://github.com/PLOS/ambra.git
 cd ambra
 git checkout generic

To build the latest war file (from the repository directory):

 cd ambra
 git pull origin generic
 mvn clean install

The new war file will be located at ambra/target/ambra*.war

Installing & Configuring Ambra

Configuring Tomcat

First, you'll need to install a Tomcat server. There are several options for doing this:

  • You can  download a zip file and install it
  • You can use your system package manager to install it. On Ubuntu, this would involve running sudo apt-get install tomcat6

For specificity, the rest of this guide will assume you have downloaded Tomcat as a zip and unpacked it to /usr/local/tomcat. If you have used a package manager to install Tomcat, the following conversions should be applied:

  • The equivalent of /usr/local/tomcat/lib will be /usr/share/tomcat6/lib
  • The equivalent of /usr/local/tomcat/conf will be /etc/tomcat6
  • The equivalent of /usr/local/tomcat/webapps will be /var/lib/tomcat6/webapps
  • The equivalent of /usr/local/tomcat/logs will be /var/log/tomcat6

As mentioned above, we will need to configure some things at the container level. The first, and easiest, is logging. Ambra expects to have log4j configuration and jar on the classpath, so we will put those into Tomcat's lib to ensure they are in the classpath for all webapps:

  • Copy  log4j.jar into /usr/local/tomcat/lib
  • Put a  log4j configuration file into /usr/local/tomcat/lib. Here are the contents of an example log4j.properties file which will log everything to the console:
    log4j.rootLogger=ERROR,consoleAppender
    
    log4j.appender.consoleAppender=org.apache.log4j.ConsoleAppender
    log4j.appender.consoleAppender.Target=System.out
    log4j.appender.consoleAppender.layout=org.apache.log4j.PatternLayout
    log4j.appender.consoleAppender.layout.ConversionPattern=%-5p %c{1} - %m%n
    
    log4j.logger.org.ambraproject=DEBUG
    log4j.logger.org.ambraproject.ambra.configuration=FATAL
    

Note that when running under tomcat, everything logged to console will be redirected to /usr/local/tomcat/logs/catalina.out

Next, we need to configure the resources which Ambra expects to be provided by the container. With Tomcat, this is done by adding them to /usr/local/tomcat/conf/context.xml. Here is an example context.xml providing the database connection and filestore:

<?xml version='1.0' encoding='utf-8'?>
<Context>
  <WatchedResource>WEB-INF/web.xml</WatchedResource>
  <Resource name="jdbc/AmbraDS"
    auth="Container"
    type="javax.sql.DataSource"
    factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
    validationQuery="SELECT 1"
    testOnBorrow="true"
    driverClassName="com.mysql.jdbc.Driver"
    username="root"
    password=""
    url="jdbc:mysql://localhost/ambra" />
 
 <Resource name="ambra/FileStore"
    type="org.ambraproject.filestore.FileStoreService"
    factory="org.ambraproject.filestore.impl.LocalFileStoreFactory"
    baseDir="/path/to/filestore"
    domain="ambra" />
</Context>

For the database configuration, the "url" parameter points to the server and database name hosting the ambra database. If your database is hosted on a remote server, you'll need to specify the port, which is usually 3306. For example:

url="jdbc:mysql://mycool.database.host:3306/ambra_db"

would be the equivalent of connecting with mysql -h mycool.database.host -D ambra_db.

We used org.apache.tomcat.jdbc.pool.DataSourceFactory as the factory class for our database connections, which allows for greater concurrency than other choices. However, this class is not included with Tomcat 6, so we'll need to add two more jars to Tomcat's lib (/usr/local/tomcat/lib):

Now, take a look at the file store configuration:

 <Resource name="ambra/FileStore"
    type="org.ambraproject.filestore.FileStoreService"
    factory="org.ambraproject.filestore.impl.LocalFileStoreFactory"
    baseDir="/path/to/filestore"
    domain="ambra" />

This configures a local file store service, which will fetch files from the disk. To ensure that this works, we need that "/path/to/filestore" be a real directory, with a subdirectory with the same name as the "domain" parameter. In this case, /path/to/filestore/ambra would need to be a real directory.

There is another option for retrieving files for ambra, and that is to use the  Mogile File System. As that's more complicated, we will only briefly debut the configuration element which would need to be put in context.xml instead of the above file store definition:

    <Resource name="ambra/FileStore"
      type="org.ambraproject.filestore.FileStoreService"
      factory="org.ambraproject.filestore.impl.MogileFileStoreFactory"
      domain="plos"
      trackers="tracker_host1:6001,tracker_host2:6001"
      maxTrackerConnections="-1"
      maxIdleConnections="2"
      maxIdleTimeMillis="10000"
      reproxyEnable="false"
      reproxyCacheSettings="3600; Last-Modified Content-Type " />

The only thing that would need to be changed is the location of the  tracker hosts

Setting up MySQL

We need a MySQL server version 5.5 or greater, to hold the Ambra database. You should name the database the same as is specified in the above Tomcat configuration.

Run attachment:ambra_schema.sql to create an Ambra schema.

Configuring Ambra

First we will tackle the application-wide configuration, which is placed at /etc/ambra/ambra.xml. Here is a minimal configuration file:

<config>
  <ambra>
    <network> 
      <hosts> 
        <default>localhost</default> 
        <ambra>${ambra.network.hosts.default}</ambra>
      </hosts> 
    </network> 
    <services>
      <ehcache>
        <configFileLocation>@@EH_CACHE_LOCATION@@</configFileLocation>
      </ehcache>
      <search>
        <server>
          <url>http://localhost:8080/solr</url>
        </server>
      </search>
      <documentManagement> 
        <ingestSourceDir>@@INGEST_DIR@@</ingestSourceDir>
        <ingestDestinationDir>@@INGESTED_DIR@@</ingestDestinationDir>
      </documentManagement> 
    </services>

    <virtualJournals>
      <templateDir>@@TEMPLATE_DIR@@</templateDir>
      <default>MyJournal</default> 
      <journals>MyJournal,MyOtherJournal</journals> 
    </virtualJournals> 
  </ambra>
</config>

Each element with @@ is something we'll need to configure.

Starting from the top, we have the ehcache config location. Download attachment:ehcache.xml and put the absolute file path to this file. This should be URL-encoded. One idiosyncrasy is that on Windows you'll need to prefix this with a slash; so if the file were located at C:\Documents and Settings\ehcache.xml, we would need to put /C:/Documents%20and%20Settings/ehcache.xml

Note the "solr" url. This configuration element needs to be present for ambra to start up, but it doesn't necessarily need to point to a valid Solr instance. To enable search, we would need to set up a Solr instance and change the value here to point to it, but we won't cover that right now.

The ingestDir and ingestDestinationDir should be valid directory paths. These do not need to be URL-encoded. These directories will hold article files that are waiting to be put into the ambra system, and those that have already been processed, respectively.

The templates must be a valid path and contains data specific to each journal in your system. It configures the journal metadata and defines its front end. See the "Templates Directory" section below.

The last step is to configure ambra to use this. By default ambra will look for /etc/ambra/ambra.xml as the file to load. You can put the above ambra.xml there, or you can add a java argument when starting up tomcat to point to this file. The argument is -Dambra.configuration=UrlToAmbraXml, e.g. -Dambra.configuration=file:///home/joe/ambra.xml

Java arguments can be added to tomcat by setting the JAVA_OPTS environment variable before starting tomcat.

You should also add -Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true to the java arguments, which will allow you to view article pages.

Here is an example JAVA_OPTS setting:

export JAVA_OPTS="$JAVA_OPTS -Xmx1024m -XX:MaxPermSize=256m \
-Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true -Dambra.configuration=file:///my/ambra/config.xml"

Templates Directory

For a quick start, save both attachment:setup_templates.sh and attachment:default_journal.xml to your templates directory, then run setup_templates.sh with your journal IDs as arguments. For example, if your journal IDs are "MyJournal" and "MyOtherJournal" as in the example ambra.xml above, you would do

sh setup_templates.sh MyJournal MyOtherJournal

This will set up the directory structure for your journals. To set it up manually instead, follow the description in the next paragraph.

The templates directory has a subdirectory named journals, which will have a subdirectory for each journal specified in the <journals> tag. Each of those should have subdirectories named configuration and webapp. For example, if we set /var/local/templates as our templateDir, and kept "MyJournal" and "MyOtherJournal" as the names of our journals, the directory structure should look like this:

/var/local/templates/journals/
                       |---> MyJournal
                       |         |---> configuration   
                       |         |---> webapp    
                       |
                       |---> MyOtherJournal           
                                 |---> configuration   
                                 |---> webapp    

Inside of each configuration directory, there should be a file named journal.xml which contains configuration specific to the journal, such as the  eIssn. If you ran setup_templates.sh with default_journal.xml in place, each journal will have a skeletal journal.xml prepopulated.

Here is an example of a filled-out journal.xml. Note the example values that will have to be replaced with real data, including "MyJournal" appearing as an XML tag name on the sixth line.

<?xml version="1.0" encoding="UTF-8" ?>
<config>
  <ambra>
    <!-- virtual journal config -->
    <virtualJournals>
      <MyJournal>
        <journal>MyJournal</journal>
        <eIssn>1234-5678</eIssn>
        <description>An Open Access Journal</description>
        <rules>
          <host>.*myjournal.*</host>
        </rules>
        <url>http://www.myjournal.org</url>
        <!-- Configuration keys for displaying recent articles tab widget on home page -->
        <recentArticles>
          <numDaysInPast>7</numDaysInPast>
          <numArticlesToShow>5</numArticlesToShow>
          <typeUriArticlesToShow>
            <articleTypeUri>http://rdf.plos.org/RDF/articleType/Research%20Article</articleTypeUri>
          </typeUriArticlesToShow>
        </recentArticles>
        <mostViewedArticles>
          <limit>5</limit>
          <timeFrame>30</timeFrame>
          <message>These articles are updated daily\, based on usage data from the previous 30 days.</message>
        </mostViewedArticles>
      </MyJournal>
    </virtualJournals>

    <freemarker>
      <!--
        # This section defines the various journals and the css and javascript files which should be
        # included on each page as well as the page title.  The values within the <default> tag are used
        # if any of the values are missing in the <page> definitions.  Note, that the title, css, and
        # javascript level values are entirely replaced, they are not additive.  Override config files
        # may define values for each of those three variables and they will supsercede values present
        # in subsequent config values.  The lookup for values is as follows:
        # 1. Page defined in journal
        # 2. Default value defined in journal
        # 3. Page defined in default journal
        # 4. Default value in default journal
        # To define an empty value for a certain page so that it doesn't use defaults, just put the
        # element tag with no value, e.g. <javascript></javascript>
      -->
      <journal>
        <name>MyJournal</name>
        <metaKeywords>things about which this journal publishes</metaKeywords>
        <metaDescription>MyJournal is a revolutionary Open Access journal built on the ambra publishing platform.</metaDescription>
        <articleTitlePrefix>MyJournal:</articleTitlePrefix>
        <displayName>MyJournal</displayName>
        <default>
          <title>MyJournal: An Open-Access Journal</title>
        </default>
      </journal>
    </freemarker>
  </ambra>
</config>

For any page, we can insert configuration specifying javascript and css files to include on the page by placing a configuration element underneath the <freeemarker> node. e.g:

        <page>
          <name>/static/scope.ftl</name>
          <css>
            <file>/css/screen.css</file>
            <file>/css/iepc.css</file>
            <file>/css/static.css</file>
            <file>/css/journal.css</file>
          </css>
          <javascript>
            <file>/javascript/dojo/dojo/dojo.js</file>
            <file>/javascript/dojo/dojo/ambra.js</file>
            <file>/javascript/init_global.js</file>
            <file>/javascript/one_awesome_script.js</file>
          </javascript>
        </page>

If there are any errors starting up mentioning unknown properties, just translate the '.'s to xml nodes. e.g. ambra.services.ehcache.configFileLocation references the ehcache node in the ambra.xml above.

Running Ambra

Once everything is configured, running Ambra is as simple as deploying the war to tomcat and starting up. You should copy an ambra war to /usr/local/tomcat/webapps/ROOT.war. Check the logs for startup messages, and then go to http://localhost:8080/

Setting up Admin

The Admin war may be downloaded and deployed side-by-side with the Ambra war. Copy it to /usr/local/tomcat/webapps/admin.war and go to http://localhost:8080/admin/ .

Default credentials for Admin

When setting up and debugging, it is useful to be able to log in to Admin without using the production CAS component. Admin has a "dummy single sign-on" feature that permits this.

To enable dummy single sign-on, edit /etc/ambra/ambra.xml and add the element <dummySsoEnabled>true</dummySsoEnabled> within the <platform> element. That is, the overall structure should look like

<config> 
  <ambra> 
    <platform> 
      <dummySsoEnabled>true</dummySsoEnabled>
    </platform>
  </ambra>
</config>

Then, run attachment:ambra_test_profile.sql against the database to create a user profile named "test" with admin rights. Finally, redeploy the war or restart Tomcat.

When you go to  http://localhost:8080/admin/ , you should now see a page titled "Dummy-SSO Login" with a login prompt. Input "test" for the "AuthId" field; you may leave the email blank. It is necessary under some circumstances to attempt to log in twice.


Home

Attachments