Getting Started Guide
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:
- Walkthrough of the Ambra core components
- Content Repo
- Obtaining the Applications
- System setup
- Setting up the databases
- Configuration files
- Running the Application
- Confirming that the application is running
- Ingesting an article
Walkthrough of the Ambra core components
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 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.
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.
- 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.
Ambra has been tested with Tomcat 7 and should be compatible with the latest Tomcat.
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
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
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");
journalKey- an identifier used in config files. A theme is set for a journal by setting
journal.yaml. For more on themes see the Themes Guide.
title- the journal title
eissn- the journal’s electronic ISSN (e-ISSN). Articles identify the journal to which they are added by e-ISSN (see the Ingestible Package Guide for details). For the sample database we will use a dummy value:
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
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
Create the following directories:
- a directory to hold configuration files
- a directory to hold files in the Content Repo’s datastore
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.
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 requires it’s own configuration file placed in the configuration directory:
It has some required fields.
context.xml in your configuration directory must contain a path to the Content Repo data store.
Wombat requires it’s own configuration file placed in the configuration directory:
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
cd $HOME/ambra/ wget https://plos.github.io/ambraproject/example/themes.tar.gz tar -xvzf themes.tar.gz
/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.
- Compile the app:
- Run the app:
mvn tomcat6:run -Dmaven.tomcat.port=8080 -Dwombat.configDir=/etc/ambra
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
http://localhost:<PORT> to view the root page for each application.
- Wombat: You should see an introductory web page at
- Rhino: You should see a Swagger API interface at
- Content Repo: You should see a Swagger API interface at
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.