[Marmotta Wiki] Update of "Installation" by SergioFernandez

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Marmotta Wiki" for change notification.

The "Installation" page has been changed by SergioFernandez:
http://wiki.apache.org/marmotta/Installation

Comment:
imported content

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

<wiki:toc />

= 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 6.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 Marmotta is to use the standalone installer, which will automatically install and configure all core components of the LMF including a version of Apache Tomcat for running the web application.

To install the standalone version, download the marmotta-installer-X.Y-standalone.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 the LMF server:
  * 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 "Marmotta"
  * on MacOS, there are two actions "Start Marmotta" and "Shutdown Marmotta" in the installation folder

After installation, you can access the administration interface of Marmotta by pointing your browser to `http://{your_host_name}:8080/marmotta` or by clicking on the Marmotta systray icon and selecting "Administration" from the menu.

= Installation (Binary) =

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

  # Download and install the application server (Tomcat 6.0.x or Jetty 6.x) and the database you intend to use (optional, default is H2 embedded)
  # Copy the .war file into the application server's deployment directory (Tomcat and Jetty: the webapps subdirectory)
  # In the console where you will start the application server, set the environment variable LMF_HOME to the directory that will be used for storing the persistent runtime data of the Linked Media Server
  # Startup the application server and go to the deployment URL with a web browser (e.g. http://localhost:8080). The Linked Media Server will then carry out initial setup using the embedded H2 database. The default interface will also contain links to the admin area and API documentation of the Linked Media Server.
  # (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 LMF_HOME every time you open
a new terminal, you can also enter it persistently by adding the following lines to catalina.sh (Unix):

{{{
export LMF_HOME=<PATH-TO-HOME>
export JAVA_OPTS="-Djava.net.preferIPv4Stack=true -Xmx1024m -XX:PermSize=128m -XX:MaxPermSize=256m -XX:+UseConcMarkSweepGC -XX:+CMSClassUnloadingEnabled"
}}}

The latter option will give more memory to the Linked Media Server. 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 ===

Believe it or not, but Tomcat can also have bugs. We recommend to use *Tomcat 6.0.33* to work with the LMF, because it is the fastest and currently most reliable version:
  * Tomcat 6.0.32 or lower contains a serious bug that does not allow to set context parameters
  * Tomcat 7.x is significantly slower and not as reliable when using CDI/Weld


=== Multiple LMF Instances ===

In some settings it might be desirable to set up multiple instances of the LMF in the same application server installation under different context URLs. This can be achieved by creating context definition files under

{{{
conf/Catalina/localhost/<appname>.xml
}}}

where `<appname>`.xml is a context configuration file. `<appname>` is the name of the web application, e.g. "Marmotta" or "MyApp". The file will contain a configuration similar to the following:

{{{
<Context docBase="/data/marmotta/build/libs/marmotta.war" unpackWAR="false" useNaming="true">
  <Parameter name="kiwi.home" value="/data/instances/lmf" override="false"/>

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

  * The docBase attribute specifies the location of the WAR file of the LMF in case it is not located in the webapps directory. 
  * The value of the parameter kiwi.home provides the location of the LMF home directory (for historical reasons called 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 [http://docs.codehaus.org/display/JETTY/JNDI 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 (Source) =

Marmotta source code can be obtained by cloning the Git repository: https://git-wip-us.apache.org/repos/asf/incubator-marmotta.git 

Additional Requirements:
  * Mercurial (http://mercurial.selenic.com/)
  * Maven 3.x (http://maven.apache.org)

Installation steps:
  # mvn install
  # cd marmotta-webapp
  # mvn tomcat7:run

The build system also works with various IDEs (Eclipse, InteliJ or Netbeans).

Maybe you could find also useful these [[DevelopmentTricks|development tricks]].


== Common Database settings == 

(change name of database if different):

H2:
  * Hibernate: org.hibernate.dialect.H2Dialect
  * Driver: org.h2.Driver
  * URL:  jdbc:h2:/tmp/kiwi/db/kiwi;MVCC=true;DB_CLOSE_ON_EXIT=FALSE

PostgreSQL:
  * Hibernate: org.hibernate.dialect.PostgreSQLDialect
  * Drver: org.postgresql.Driver
  * URL:  jdbc:postgresql://localhost:5432/lmf

MySQL:
  * Hibernate: org.hibernate.dialect.MySQLDialect
  * Driver: com.mysql.jdbc.Driver
  * URL:  jdbc:mysql://localhost:3306/lmf