svn commit: r1448175 - /incubator/marmotta/site/trunk/content/markdown/installation.md

[wi...@apache.org]

Author: wikier
Date: Wed Feb 20 14:10:59 2013
New Revision: 1448175

URL: http://svn.apache.org/r1448175
Log:
added full installation documentation

Modified:
    incubator/marmotta/site/trunk/content/markdown/installation.md

Modified: incubator/marmotta/site/trunk/content/markdown/installation.md
URL: http://svn.apache.org/viewvc/incubator/marmotta/site/trunk/content/markdown/installation.md?rev=1448175&r1=1448174&r2=1448175&view=diff
==============================================================================
--- incubator/marmotta/site/trunk/content/markdown/installation.md (original)
+++ incubator/marmotta/site/trunk/content/markdown/installation.md Wed Feb 20 14:10:59 2013
@@ -35,31 +35,123 @@ 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
 
-After installation, you can access the administration interface of Marmottta by pointing your browser to 
-[http://localhost:8080/](http://localhost:8080/) or by clicking on the Marmotta systray icon and selecting 
-"Administration" from the menu.
+After installation, you can access the administration interface of Marmottta by pointing your 
+browser to [http://localhost:8080/](http://localhost:8080/) or by clicking on the Marmotta 
+systray icon and selecting "Administration" from the menu.
 
-# Installation (binary)
+## Installation (binary)
 
-@@TODO@@
+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:
 
-# Installation (maven)
+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 `LMF_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.
 
-@@TODO@@
+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):
 
-# Installation (source)
+    export LMF_HOME=<PATH-TO-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 we recommend to use Tomcat >= 7.0.35 
+to work with Marmotta.
+
+#### 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="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>
+
+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 `kiwi.home` provides the location of Marmotta home directory (for [historical reasons](http://code.google.com/p/lmf/wiki/VersionNumbering) 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 Jetty Documentation](http://docs.codehaus.org/display/JETTY/JNDI).
+
+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 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.0.0-incubating-SNAPSHOT 
+
+Afterwards, change to the newly created project directory and run:
+
+    mvn clean tomcat7:run
+
+To start a clean Marmotta installation.
+
+## 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/incubator-marmotta.git marmotta
-    cd marmotta
+    cd marmotta/
     mvn clean install
 
+In case you would need a quick build, you may want to avoid running tests:
+
+    mvn clean install -DskipTests -Dmaven.test.skip=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/webapp
+    cd launchers/marmotta-webapp/
     mvn tomcat7:run
 
-This will launch Marmotta on an embedded Tomcat running at [http://localhost:8080/](http://localhost:8080/).
+This will launch Marmotta in an embedded Tomcat server running at [http://localhost:8080/](http://localhost:8080/).