docs/manual-installation.adoc

= Manual Installation
:index-group: OpenEJB Standalone Server
:jbake-date: 2018-12-05
:jbake-type: page
:jbake-status: published


== Overview

The manual installation process is significantly harder then the
link:tomcat.html[automatic installation] which we normally recommend. In
this installation process you will do the following:

[arabic]
. Install openejb.war
. Download openejb.war from the
http://tomee.apache.org/downloads.html[download page]
. Make webapps/openejb directory
. Change to new webapps/openejb directory
. Unpack the openejb.war file in the new directory
. Add the OpenEJB listener the conf/server.xml file
. Update the non-compliant Tomcat annotations-api.jar
. Add the OpenEJB JavaAgent to the bin/catalina.bat or bin/catalina.bat
script

== Install openejb.war

Once Tomcat has been link:tomcat-installation.html[installed] , the
OpenEJB plugin for Tomcat can be installed. The war can be obtained from
the http://tomee.apache.org/downloads.html[download page]

The commands in this example are executed from within the Tomcat
installation directory.

== Unpack OpenEJB Tomcat plugin in Tomcat webapps directory

Be careful, this is the most error prone step. A web application does
not contain a root directory, so if you unpack it in the wrong
directory, it is difficult to undo. Please, follow this step closely,
and most importantly make sure you execute the unpack command from
within the new webapps/openejb directory

Due to the structure of war files, you must create a new directory for
OpenEJB, change to the new directory and execute the unpack command from
within the new directory. If you get this wrong, it is difficult to
undo, so follow the steps closely.

== Add the OpenEJB listener to Tomcat

All Tomcat listener classes must be available in the Tomcat common class
loader, so the openejb-loader jar must be copied into the Tomcat lib
directory.

[source,java]
----
    C:\apache-tomcat-6.0.14>copy webapps\openejb\lib\openejb-loader-3.0.0-SNAPSHOT.jar lib\openejb-loader.jar
    1 file(s) copied.

    apache-tomcat-6.0.14$ cp webapps/openejb/lib/openejb-loader-*.jar lib/openejb-loader.jar
----

Add the following
`<Listener className="org.apache.openejb.loader.OpenEJBListener" />` to
your conf/server.xml file to load the OpenEJB listener:

The snippet is shown below

[source,xml]
----
<!-- Note:  A "Server" is not itself a "Container", so you may not
define subcomponents such as "Valves" at this
level.
Documentation at /docs/config/server.html
 -->

<Server port="8005" shutdown="SHUTDOWN">
<!-- OpenEJB plugin for tomcat -->
<Listener
className="org.apache.openejb.loader.OpenEJBListener" />

<!--APR library loader. Documentation at /docs/apr.html -->    
<Listener
className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />
----

== Update the Tomcat annotations-api.jar file

Tomcat contains an old non-compliant version of the javax.annotation
classes and these invalid classes must be updated so OpenEJB can process
annotations. Simply, replace the annotations-api.jar in the Tomcat lib
directory with the updated annotations-api.jar in the OpenEJB war.

== Add OpenEJB javaagent to Tomcat startup

OpenJPA, the Java Persistence implementation used by OpenEJB, currently
must enhanced persistence classes to function properly, and this
requires the installation of a javaagent into the Tomcat startup
process.

First, copy the OpenEJB JavaAgent jar into the lib directory.

Simply, add the snippet marked below in bin/catalina.bat (Windows) or
bin/catalina.sh (Unix) file to enable the OpenEJB javaagent:

[source,properties]
----
if not exist "%CATALINA_BASE%\conf\logging.properties" goto noJuli
set JAVA_OPTS=%JAVA_OPTS%
-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager
-Djava.util.logging.config.file="%CATALINA_BASE%\conf\logging.properties"
:noJuli

 # Start of Snippet to add
 rem Add OpenEJB javaagent if not exist
 "%CATALINA_BASE%\webapps\openejb\lib\openejb-javaagent.jar" goto
 noOpenEJBJavaagent set
 JAVA_OPTS="-javaagent:%CATALINA_BASE%\webapps\openejb\lib\openejb-javaagent.jar"
 %JAVA_OPTS% :noOpenEJBJavaagent
 # End of Snippet to add


rem ----- Execute The Requested Command
---------------------------------------
echo Using CATALINA_BASE:   %CATALINA_BASE%
echo Using CATALINA_HOME:   %CATALINA_HOME%



# Set juli LogManager if it is present
if [OPENEJB: -r "$CATALINA_BASE"/conf/logging.properties ](openejb:--r-"$catalina_base"/conf/logging.properties-.html)
; then
JAVA_OPTS="$JAVA_OPTS
"-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager"
"-Djava.util.logging.config.file="$CATALINA_BASE/conf/logging.properties"
fi

 #Start of Snippet to add
 if [OPENEJB: -r "$CATALINA_BASE"/webapps/lib/openejb-javaagent.jar ](openejb:--r-"$catalina_base"/webapps/lib/openejb-javaagent.jar-.html)
; then
JAVA_OPTS=""-javaagent:$CATALINA_BASE/lib/openejb-javaagent.jar"
$JAVA_OPTS"
fi
#End of Snippet to add
----

== Note: The example above is an excerpt from the middle of the
bin/catalina.sh file. Search for the this section and add the snippet
shown