View source for Installation/Custom/Apache Tomcat

{| style="margin: auto;" cellpadding="0"
|- align="center"

| <div class="t"><div class="b"><div class="l"><div
class="r"><div class="bl"><div class="br"><div class="tl"><div
class="tr">
<div style="height:25px;display:
table-cell;vertical-align:middle;"><span style="color:#DC6710">[[Installation | Installation]]</span></div>
</div></div></div></div></div></div></div></div>

| <div class="t"><div class="b"><div class="l"><div
class="r"><div class="bl"><div class="br"><div class="tl"><div
class="tr">
<div style="height:25px;display:
table-cell;vertical-align:middle;"><span style="color:#DC6710">[[Installation/Custom | Custom installation]]</span></div>
</div></div></div></div></div></div></div></div>

| 

{| 
|- 

<div class="t"><div class="b"><div class="l"><div class="r"><div
class="bl"><div class="br"><div class="tl"><div class="tr">
<div style="height:25px;display:
table-cell;vertical-align:middle;"><span style="color:#DC6710">[[Installation/Custom/PostgreSQL_Database | PostgreSQL]]</span>
</div></div></div></div></div></div></div></div></div>

| <div class="t"><div class="b"><div class="l"><div
class="r"><div class="bl"><div class="br"><div class="tl"><div
class="tr">
<div style="height:25px;display:
table-cell;vertical-align:middle;"><span style="color:#DC6710">[[Installation/Custom/Oracle_Database | Oracle]]</span></div></div></div></div></div></div></div></div></div>

|}

| <div class="t"><div class="b"><div class="l"><div
class="r"><div class="bl"><div class="br"><div class="tl"><div
class="tr">
<div style="height:25px;display:
table-cell;vertical-align:middle;"><span style="color:#DC6710">[[Installation/Custom/JDK | JDK]]</span></div></div></div></div></div></div></div></div></div>

| <div class="t"><div class="b"><div class="l"><div
class="r"><div class="bl"><div class="br"><div class="tl"><div
class="tr">
<div style="height:25px;display:
table-cell;vertical-align:middle;"><span style="color:#DC6710">[[Installation/Custom/Apache_Tomcat | Tomcat]]</span></div></div></div></div></div></div></div></div></div>

| <div class="t"><div class="b"><div class="l"><div
class="r"><div class="bl"><div class="br"><div class="tl"><div
class="tr">
<div style="height:25px;display:
table-cell;vertical-align:middle;"><span style="color:#DC6710">[[Installation/Custom/Apache_Ant | Ant]]</span></div></div></div></div></div></div></div></div></div>

| <div class="t"><div class="b"><div class="l"><div
class="r"><div class="bl"><div class="br"><div class="tl"><div
class="tr">
<div style="height:25px;display:
table-cell;vertical-align:middle;"><span style="color:#DC6710">[[Installation/Custom/Apache | Apache]]</span></div></div></div></div></div></div></div></div></div>

| 

{| 
|- 

<div class="t"><div class="b"><div class="l"><div class="r"><div
class="bl"><div class="br"><div class="tl"><div class="tr">
<div style="height:25px;display:
table-cell;vertical-align:middle;"><span style="color:#DC6710">[[Installation/Custom/Download_Tarball | Download Tarball]]</span>
</div></div></div></div></div></div></div></div></div>

| <div class="t"><div class="b"><div class="l"><div
class="r"><div class="bl"><div class="br"><div class="tl"><div
class="tr">
<div style="height:25px;display:
table-cell;vertical-align:middle;"><span style="color:#DC6710">[[Installation/Custom/Mercurial_Clone | Mercurial Clone]]</span></div></div></div></div></div></div></div></div></div>

|}

| <div class="t"><div class="b"><div class="l"><div
class="r"><div class="bl"><div class="br"><div class="tl"><div
class="tr">
<div style="height:25px;display:
table-cell;vertical-align:middle;"><span style="color:#DC6710">[[Installation/Custom/Openbravo_Setup | Openbravo Setup]]</span></div></div></div></div></div></div></div></div></div>

|}

== Apache Tomcat Requirements ==

Openbravo needs the Apache Tomcat to be installed and configured.

For the specific versions supported and the currently recommended version check the [[System_Requirements#Server:_software_stack|System Requirements]].

=== User account for running tomcat / compiling ===

Conceptually there are two user accounts involved in working with Openbravo:
* command-line user used to work with files & compile Openbravo
* user account used by Apache Tomcat service

There are several overlapping areas in which one of the accounts needs to access and modify files from the other account in both directions.

To avoid any problems Openbravo strongly recommends to run Apache Tomcat services with the same user account which is used on command line. As that way the above topic will be perfectly solved easily.

=== Download and install Apache Tomcat ===

Apache Tomcat distribution can be downloaded from the official [https://tomcat.apache.org/ project] page.

To install it extract the archive to a folder on your system. Make sure that all files are owned the by main user 'openbravo' as explained above.

{{(!)|Downloading Tomcat distribution instead of taking packaged version from i.e. a Linux Distribution has the downside of not having a init script and not having it integrated into the boot process. Init scripts are quite custom to the i.e. linux system being used so creating one is up to the system administrator and not explained in this guide. }}

=== Environment variables to configure ===

Three environment variables must be configured for correct operation:
* CATALINA_HOME must point to the tomcat installation folder selected above
* CATALINA_BASE must also point to the tomcat installation folder selected above
* CATALINA_OPTS must set a java max heap size of at least 1GB

=== Tomcat config files to modify ===

==== Changes to conf/context.xml ====

Two changes are required to the context.xml file:

In order to avoid Tomcat from auto-reloading itself, comment out the WatchedResource line:
<source lang="xml"><!-- <WatchedResource>WEB-INF/web.xml</WatchedResource> --></source>

Disable session persistence as it is not supported and cannot work with Openbravo.
For this activate the following config which is present but commented in the tomcat default installation:

<source lang="xml"><!-- <Manager pathname="" /> --></source>

==== Changes to conf/server.xml for development use ====

As "development use" here is meant a simple installation of tomcat without another http server like Apache Webserver in front of it.

The AJP connector on port 8009 active by default in tomcat download should be activated. For this its entry should be commented out.

Optionally disable the tomcat access log if you do not want to have a access log file with one line for every http request. To do this disable the AccessLogValve  entry present by default in tomcat distribution.

==== Changes to conf/server.xml  for production use ====

Production use here means a Apache HTTP server in front of tomcat to take care of several extra tasks as:
* Compression of http responses
* https/ssl for security
* Taking care of serving static resources without tomcat

Having a webserver in front means the direct http connector on port 8080 of tomcat is not used and should be disabled by commenting out its entry.

<source lang="xml"><!-- <Connector port="8080" redirectPort="8443" connectionTimeout="20000" protocol="HTTP/1.1"/> --></source>

This guide assumes the Apache HTTP webserver is installed on the same server, so the connector port 8009 should be restricted to be accessible only locally.

In the ''AJP Connector on port 8009'' add the following attribute:
* address="localhost"

Also disable the builtin tomcat access log as the Apache server in front of it has one also with more information already. For this comment out the following line:
<source lang="xml"><!-- <Valve className="org.apache.catalina.valves.AccessLogValve" pattern="%h %l %u %t "%r" %s %b" suffix=".txt" prefix="localhost_access_log." directory="logs"/> --></source>

=== Remove other tomcat default webapps ===

Default ships several web-application by default in its webapps folder:
* ROOT tomcat default landing page
* docs tomcat documentation
* examples some code examples
* host-manager & manager web-based applications to manage tomcat itself.

A typical openbravo installation does not require any of those. To slim-down / lock-down the installation those should be removed by deleting their folders from tomcat webapps directory.

If a custom install should want to keep any of those access control should be put in place to avoid any unauthorized usage.

=== Example Install on Ubuntu 18.04 LTS ===

Get direct download link for latest tomcat 8.5.x from tomcat page.

Download tomcat to /opt/tomcat
<source lang="bash">sudo su -  
cd /tmp
wget <copied_link_address>
tar xvf apache-tomcat-<version>.tar.gz
mv /tmp/apache-tomcat-<version> /opt/tomcat
chown openbravo: -R /opt/tomcat
</source>

Configure the required environment variables:
<source lang="bash">sudo su -
# set CATALINA_OPTS
echo 'export CATALINA_OPTS="-server -Djava.awt.headless=true -Xms384M -Xmx1024M"' > /etc/profile.d/tomcat.sh

# set CATALINA_HOME and CATALINA_BASE
echo 'export CATALINA_HOME=/opt/tomcat' >> /etc/profile.d/base-variables.sh
echo 'export CATALINA_BASE=/opt/tomcat' >> /etc/profile.d/base-variables.sh
</source>

Apply required config file changes
<source lang="bash">sudo su -
# Apply config changes as per documentation above (for production use)
vim /opt/tomcat/conf/context.xml
vim /opt/tomcat/conf/server.xml
</source>

Not having an init-script allow to start / stop tomcat using the following.
It is important to always us the correct user account to start / stop tomcat!

<source lang="bash">sudo su - openbravo
cd /opt/tomcat
# to start
bin/startup.sh
# to stop
bin/shutdown.sh
</source>





=== Example install of Apache Tomcat on Microsoft Windows ===

{{(!)|This section was written for an older version and it outdated. It is kept as a reference but should not be just used 'as written'}}

#Download and install [http://tomcat.apache.org/download-70.cgi Apache Tomcat].
#The download you want is the ''32-bit/64-bit Windows Service Installer'', as that will integrate it as Windows Service.
##Run that installer.
##It will ask if it should install several optional components (documentation, manager application, host manager application, example application). Openbravo does not need any of those they should not be marked.
##For the port configuration the rest of the guide assumes the standard ports 8005, 8080, 8009.
#Add '''CATALINA_HOME''', '''CATALINA_BASE''' and '''CATALINA_OPTS''' environment variables:
##Right-click on '''My Computer'''.
##Select '''Properties'''. The system properties window appears.
##Select the '''Advanced''' tab.
##Click '''Environment Variables'''.
##Click '''New'''. The New System Variable box appears.
##In the '''Variable name''' field, type ''CATALINA_HOME''.
##In the '''Variable value''' field, type the path of the Apache Tomcat installation directory. This is usually ''C:\Apache Software Foundation\Tomcat 7.0''.
##Click '''OK'''.
##Click '''New'''. The New System Variable box appears.
##In the '''Variable name''' field, type ''CATALINA_BASE''.
##In the '''Variable value''' field type ''%CATALINA_HOME%''.
##Click '''OK'''
##Click '''New'''. The New System Variable box appears.
## In the '''Variable name''' field, type ''CATALINA_OPTS''.
##In the '''Variable value''' type ''-server -Djava.awt.headless=true -Xms384M -Xmx1024M''.
#Configure values in the tomcat service manager application. After the installation there will be a new icon in the windows ''System Tray'' which can be used to start / stop the tomcat service and also configure it.
##In the configure window, go to the Java tab
###Add ''-server -Djava.awt.headless=true'' to the end of the Java Options
###Change the ''Initial Memory Pool'' to 384M
###Change the ''Maximum Memory Pool'' to 1024M

As you will have noticed that item 4 above makes sure that the settings just done now match the ones done via the ''CATALINA_OPTS'' variable.

If you change any one of the two later it is important to edit then in both places.

{{(!)| More information about managing environment variables in Microsoft's [http://support.microsoft.com/kb/310519 Help & Support] site}}
{{(!)| Known issue (for releases before 3.0PR15Q1)
{{IssueReference|issuenum=16452}}: On Windows Openbravo won't start if the installation path contains a space }}

#In order to avoid Tomcat from auto-reloading itself, comment the WatchedResource line in ''C:\Apache Software Foundation\Tomcat 7.0\conf\context.xml'':
#:<source lang="xml"><!-- <WatchedResource>WEB-INF/web.xml</WatchedResource> --></source>
#On startup Tomcat will try to load active session from before last shutdown again. As that is not supported and cannot work with Openbravo switch it off by uncommenting the following line in the same context.xml file:
#:<source lang="xml"><!-- <Manager pathname="" /> --></source>

You can check that Tomcat is running by opening http://localhost:8080 in a web browser.

==== Installing for development use (non production) ====

As development use here is meant a simple installation of tomcat without another Http server like Apache in front of it.

In addition to the global config above the following changes should be done.

# In the config/server.xml file of tomcat comment out the ''Connector entry for AJP on port 8009'' as that is not useful without a Apache server in front of it.
# For the ''Http Connector on port 8080'' add the following attribute to it:
## URIEncoding="UTF-8"
#Optionally disable the tomcat access log if you do not want to have a access log file with one line for every http request. For this comment out the following line:
<source lang="xml"><!-- <Valve className="org.apache.catalina.valves.AccessLogValve" pattern="%h %l %u %t "%r" %s %b" suffix=".txt" prefix="localhost_access_log." directory="logs"/> --></source>

==== Installing for production use ====

Production use here means a Apache HTTP server in front of tomcat to take care of several extra tasks as:
* Compression of http responses
* https/ssl for security
* Taking care of serving static resources without tomcat

In addition to the global config above the following changes should be done.

# In the config/server.xml file of tomcat comment out the ''Http Connector entry for port 8080'' as it will not be used at all.
<source lang="xml"><!-- <Connector port="8080" redirectPort="8443" connectionTimeout="20000" protocol="HTTP/1.1"/> --></source>
# For the ''AJP Connector on port 8009'' add the following two attributes to it:
## URIEncoding="UTF-8"
## address="localhost"
#Also disable the builtin tomcat access log as the Apache server in front of it has one also with more information already. For this comment out the following line:
<source lang="xml"><!-- <Valve className="org.apache.catalina.valves.AccessLogValve" pattern="%h %l %u %t "%r" %s %b" suffix=".txt" prefix="localhost_access_log." directory="logs"/> --></source>

==== How to use the installed Tomcat ====

This questions tries to address some frequently asked questions.

* The tomcat service installed above is configured as a Windows Service. Also a small service manager application is installed and auto-started.
* To start/stop tomcat either use this service manager application in the System Tray or the normal windows service manager.
* To control the service auto-start on boot modified the 'Start Type' parameter of this service to the either ''Automatic'' or ''Manual''. This setting can be configured either using the System Tray Application or the normal windows service manager.
* The tomcat log files (including the openbravo.log) can be found in the ''logs'' subfolder of the tomcat installation
** Tomcat startup log can be found in the tomcat7-srderr.<current date> file
** Normal openbravo log entries can be found as usual in the openbravo.log & openbravo_hibernate.log files

[[Category:Installation]]