This project has retired. For details please refer to its Attic page.
Apache Marmotta - Installing Apache Marmotta

Installing Apache Marmotta

Apache Marmotta is implemented as a Java Web Application that can, in principle, be deployed to any Java Application Container. It has been tested under Jetty 6.x and Tomcat 7.x. It can be installed using the source code or as a binary package.

After installation remember not to access using a local hostname or IP address until you have accessed using its correct external hostname (see configuration for further details).

Requirements

  • Hardware
  • standard workstation (Dual-Core or similar)
  • 1GB main memory
  • about 100MB hard disk
  • Software
  • Java JDK 6 or higher
  • Java Application Server (Tomcat 7.x or Jetty 6.x)
  • Database (PostgreSQL, MySQL - if not explicitly configured, an embedded H2 database will be used)

Installation (standalone)

The most straightforward way of installing the Marmota is to use the standalone installer, which will automatically install and configure all core components of Marmotta, including a version of Apache Tomcat for running the web application.

To install the standalone version, download the marmotta-installer-x.y.z.jar file from the downloads section and execute the jar file (double click or java -jar command).

IMPORTANT: The installation path on windows systems may not contain whitespaces (e.g. 'C:/Program Files' is not usable). This is a serious bug of Tomcat application server and will most probably be fixed in further versions.

Depending on the underlying operating system, the installer will also create shortcuts for starting/stopping Marmotta:

  • on Windows, these can be found in the Start Menu under “Apache -> Marmotta”
  • on Linux, these are created on the desktop and also in the Applications menu under “Apache Marmotta”
  • on MacOS, there are two actions “Start Marmotta” and “Shutdown Marmotta” in the program folder of the Marmotta installation

Installation (binary)

The binary installation comes as a Java Web Archive (.war) file that can be deployed in any JavaEE application server. The deployment procedure is as follows:

  1. Download and install the application server (Tomcat 7.0.x or Jetty 6.x) and the database you intend to use (optional, default is H2 embedded)
  2. Set the environment variable MARMOTTA_HOME to the directory that will be used for storing the persistent runtime data of Marmotta
  3. Deploy the .war file into the application server, copyint into deployment directory (Tomcat and Jetty: the webapps subdirectory) or whatever method provided
  4. Startup the application server and go to the deployment URL with a web browser (e.g. http://localhost:8080). Marmotta will then carry out initial setup, using an embedded H2 database by default. The default interface will also contain links to the admin area and API documentation.
  5. (OPTIONAL) If you do not want to use H2, go to the admin interface and configure the database according to your own preferences. It is recommended that you restart the application server when you have done so.

To avoid setting the environment variable MARMOTTA_HOME every time you open a new terminal, you can also enter it persistently by adding the following lines to catalina.sh (Unix):

export MARMOTTA_HOME=/path/to/marmotta/home
export JAVA_OPTS="-Djava.net.preferIPv4Stack=true -Xmx1024m -XX:PermSize=128m -XX:MaxPermSize=256m -XX:+UseConcMarkSweepGC -XX:+CMSClassUnloadingEnabled -XX:+UseConcMarkSweepGC -XX:+HeapDumpOnOutOfMemoryError"

The latter option will give more memory to Marmotta; you can even increase the value of 1024 to something higher as needed.

Specific Settings for Tomcat

In production environments, Apache Tomcat will be the application server of choice. This is a collection of issues arising with Tomcat installations.

Tomcat Versions

Tomcat 6.0.x used to be significantly faster and reliable, but that is not true anymore. So we strongly recommend to use Tomcat 7.0.x,. Precisely Marmotta requires to run under a Servlet API 3.0 compatible container, so Tomcat >= 7.0.30 is required.

Multiple instances

In some settings it might be desirable to set up multiple instances of Marmotta in a shared application server installation under different contexts. This can be achieved by creating context definition files under conf/Catalina/localhost/{NAME}.xml, where {NAME}.xml is a context configuration file. {NAME}` is the name of the web application, e.g. “marmotta” or “myapp”. The file will contain a configuration similar to the following:

<Context docBase="/path/to/marmotta.war" unpackWAR="false" useNaming="true">

  <Parameter name="marmotta.home" value="/path/to/marmotta/home" override="false"/>

  <Resource name="BeanManager" auth="Container"
            type="javax.enterprise.inject.spi.BeanManager"
            factory="org.jboss.weld.resources.ManagerObjectFactory"
   />

</Context>

Where:

  • The docBase attribute specifies the location of the WAR file of Marmotta in case it is not located in the webapps directory.

  • The value of the parameter marmotta.home provides the location of Marmotta home directory (formerly called lmf.home or kiwi.home).

  • The Resource registers a factory for creating the Java EE 6 Bean Manager. This entry will typically remain unchanged, but it is necessary for the system to work properly.

Specific Settings for Jetty

Marmotta uses JNDI for looking up services. While most application servers have this enabled by default, Jetty needs a little bit of setup to enable JNDI functionality. The procedure is described in the Jetty Documentation.

In short, what you need to do is to copy the plus-settings from the jetty-plus.xml file to the jetty.xml file:

<Array id="plusConfig" type="java.lang.String">
  <Item>org.mortbay.jetty.webapp.WebInfConfiguration</Item>
  <Item>org.mortbay.jetty.plus.webapp.EnvConfiguration</Item>
  <Item>org.mortbay.jetty.plus.webapp.Configuration</Item>   
  <Item>org.mortbay.jetty.webapp.JettyWebXmlConfiguration</Item>
  <Item>org.mortbay.jetty.webapp.TagLibConfiguration</Item>
</Array>

and then add the option

<Set name="configurationClasses"><Ref id="plusConfig"/></Set>

to the call of org.mortbay.jetty.deployer.WebAppDeployer (search jetty.xml for it).

Installation (maven)

It is easy to build custom projects based on the Marmotta using a Maven archetype. To create a custom web project, simply run the following command and enter the base information when prompted:

mvn archetype:generate \
    -DarchetypeGroupId=org.apache.marmotta \
    -DarchetypeArtifactId=marmotta-archetype-webapp \
    -DarchetypeVersion=3.3.0 

Afterwards, change to the newly created project directory and run:

mvn clean tomcat7:run

To start a clean Marmotta installation.

Installation (debian)

If you are using any Debian-based system (Ubuntu for example), you can install Marmotta as part of the Linked Data Stack.

For that, first you need to add a new repository entry to /etc/apt/sources.list:

deb http://stack.linkeddata.org/deb/ ldstack main

Now the local package list needs to be refreshed:

sudo apt-get update

And then you can install Marmotta as a normal Debian package:

sudo apt-get install marmotta

Marmotta web application will be deployed on Tomcat 7, commonly accessible at: http://localhost:8080/marmotta

Installation (docker)

If you want to run it in Docker, there is a public image ready to use with PostgreSQL configured:

docker pull apache/marmotta
docker run -p 8080:8080 apache/marmotta

and then access localhost:8080/marmotta.

Futher details, including the Dockerfile, in the source code documentation.

Installation (source)

Considering you have git and maven installed, you just need to run the following commands:

git clone https://git-wip-us.apache.org/repos/asf/marmotta.git marmotta
cd marmotta/
mvn clean install

In case you would need a quick build, you may want to avoid running all tests:

mvn clean install -DskipTests=true

And then you’d have all artifact installed in your local Maven repository. Therefore you would be able to run the webapp launcher:

cd launchers/marmotta-webapp/
mvn tomcat7:run

This will launch Marmotta in an embedded Tomcat server running at http://localhost:8080/.

By default Marmotta uses for its home a path under the temporal directory of the system; which you may want to customized by running it specifying a custom path:

mvn tomcat7:run -Dmarmotta.home=/path/to/marmotta/home

If you want to build a WAR for deploying Marmotta to any other container, you would just need to execute:

mvn package

and then you will find it at target/marmotta.war.