Getting Started Guide

Introduction

This guide provides basic instructions for setting up a new instance of the Ambra stack.

These instructions are targeted at Linux and MacOS systems. It has not been tested in Windows environments.

Table of Contents:

  1. Walkthrough of the Ambra core components
    1. Wombat
    2. Rhino
    3. Content Repo
  2. Obtaining the Applications
  3. System setup
    1. Requirements
    2. Setting up the databases
    3. Directories
    4. Configuration files
  4. Running the Application
  5. Confirming that the application is running
  6. Ingesting an article

Walkthrough of the Ambra core components

Wombat

Wombat is the front-end component of the publishing platform. Wombat is a web application that pulls most of its article data from Rhino, and displays it using customizable FreeMarker templates. Since Wombat gets its data from Rhino, you will need a Rhino server running first.

Rhino

Rhino is the back-end service for ingesting and storing article content and metadata. Rhino provides an API to create, read, update, and delete articles and associated data.

Content Repo

The Content Repo is an append-only repository of article assets, including the manuscript XML and all images.

Obtaining the Applications

Download the source code

You can check out the source code and run the applications with Tomcat and Maven. The source repositories are here:

Alternative: Download the compiled releases

You can deploy Ambra in Tomcat without compiling the source code. Download the releases here:

Alternative: Docker Quickstart

See our Docker setup guide to quickly bring up an auto-configured Ambra stack.

System setup

Requirements

Overview

  1. Java 8
  2. Tomcat
  3. MySQL

Java 8

Your runtime environment must support Java 8 or later. To develop and compile the webapps, the Java 8 Development Kit (JDK8) is required.

Tomcat

Ambra has been tested with Tomcat 7 and should be compatible with the latest Tomcat.

MySQL

Ambra requires a running MySQL server. It has been tested with version 5.6.28 and should be compatible with the latest version of MySQL.

Setting Up the Databases

Ambra database

mysql -uroot -e "DROP DATABASE IF EXISTS ambra;"
mysql -uroot -e "CREATE DATABASE ambra;"

Download the Ambra schema (ambra-schema.sql) and import it into the ambra database:

mysql -h 127.0.0.1 -P 3306 -uroot -p ambra < ambra-schema.sql

Add a journal to the database:

INSERT INTO journal (`journalKey`, `title`, `eissn`) VALUES ("my_journal", "My Journal", "0000-0000");

Content Repo database

mysql -uroot -e "DROP DATABASE IF EXISTS repo;"
mysql -uroot -e "CREATE DATABASE repo;"

Download the Content Repo schema (content-repo-schema.sql) and import it into the repo database:

mysql -h 127.0.0.1 -P 3306 -uroot -p repo < content-repo-schema.sql

Add a bucket named “corpus” to the database.

INSERT INTO buckets (`bucketName`) VALUES ("corpus");

Setting Up Configuration

Directories

Create the following directories:

  mkdir $HOME/ambra
  mkdir $HOME/ambra/config           # configuration directory
  mkdir $HOME/ambra/crepo_datastore  # Content Repo datastore directory

On a production system, /etc/ambra is recommended for the configuration directory.

Configuration files

Shared

Rhino, Wombat, and Content Repo all run on Tomcat. For this quick start they will all run on the same Tomcat server and they will share the same context.xml (example). Place this file in the configuration directory you created above.

Rhino

Rhino requires it’s own configuration file placed in the configuration directory: rhino.yaml (example). It has some required fields.

Content Repo

The shared context.xml in your configuration directory must contain a path to the Content Repo data store.

Wombat

Wombat requires it’s own configuration file placed in the configuration directory: wombat.yaml (example). It has some required fields.

Wombat can be themed and requires a default theme to be present. Create the theme by downloading and extracting the following archive themes.tar.gz.

cd $HOME/ambra/
wget https://plos.github.io/ambraproject/example/themes.tar.gz
tar -xvzf themes.tar.gz

Edit /etc/ambra/wombat.yaml and replace $HOME with the actual path to your home directory:

cd $HOME
pwd # This prints the path to your home directory. Edit the file /etc/ambra/wombat.yaml and replace $HOME with this path.

For more on themes see the Themes Guide and Working with PLOS’s Themes .

Running the Application

Running the application from source code with Maven

Use Maven to run the applications from source. For each respective app you must be in the checked-out repository directory.

  1. Compile the app: mvn install
  2. Run the app:
    • Wombat: mvn tomcat6:run -Dmaven.tomcat.port=8080 -Dwombat.configDir=/etc/ambra
    • Rhino: mvn tomcat6:run -Dmaven.tomcat.port=8082 -Drhino.configDir=/etc/ambra
    • Content Repo: mvn tomcat6:run -Dmaven.tomcat.port=8081

Alternative: Deploying a compiled release to Tomcat

You should be familiar with how to deploy a webapp to Tomcat. Typically, .war files are simply copied into Tomcat’s webapps directory and Tomcat will start the webapp automatically.

Confirming that the application is running

Go to http://localhost:<PORT> to view the root page for each application.

Ingesting an article

PLOS provides some sample article package zip files for ingestion, located here.

You can ingest and publish an article package using Rhino’s Swagger interface. For complete instructions, see “Ingesting the article into Rhino” in the Ingestible Package Guide.