Configuring the Server Memory Settings for Essential

One of the most common issues with setting up Essential is getting the memory configuration of the various components configured correctly. As the complexity of the Essential meta-model and of Essential Viewer has increased then so have the memory resources required by the server to support them.

Right now, our current recommendation for a server is a multi-core processor such as an i5/i7 or Xeon equivalent and more importantly plenty of RAM. 4GB is a minimum but 8GB is more practical. You’ll struggle to use the Import Utility and Viewer together on a system with only 4GB of RAM. Assuming you’re running all the components on the same server (which is perfectly fine and can yield great performance) then here’s how we’d allocate the RAM across the main components…

  • Tomcat running Essential Viewer – 2GB RAM
  • Tomcat running Essential Import Utility – 2GB RAM
    • We’d install the Essential Import Utility on a separate instance running on different port e.g. 9080 as it improves stability and performance
    • If running both on a single instance then allocate 4GB RAM to Tomcat
  • Protege – 1.5GB RAM
  • If running a Database configuration we’ll ensure there’s about 1GB for that
  • We need some memory for the OS to run smoothly so about 1GB for that

This adds up to about 7.5GB. In reality, you’ll rarely use all that RAM simultaneously however this configuration is one we’ve used countless times with excellent performance.

So, now you’ve got plenty of RAM then how do you configure the components to use that.

First up, make sure you’re using the 64bit versions of all your components. If you’re running 32bit versions, you’ll max out a 1.5GB which will work whilst the repository is small but will cause you problems later on.

Protege

On Windows:

  1. Start Protege. Go to File->Preferences->Protege.lax
  2. Update the row for the property ‘lax.nl.java.option.java.heap.size.max
  3. This is set in bytes, so set this to 2048000000 for installs with the 64-bit Java environment.
  4. Click OK
  5. Restart Protege

On Mac:
If you run Protege on a Mac by double clicking an icon, you need to edit the Info.plist file that is hidden within that icon. Right click the icon (or ^-click for one button mouses) and click “show package contents”. A new finder window will come up. Double click “Contents” and then “Info.plist”. Traverse down the tree as follows: “Root” –> “Java” –> “VMOptions”. In VMOptions edit the -Xmx line to indicate the correct memory usage, e.g. 2048M. Note that this can be specified in megabytes by using the ‘M’ value.

For example, here are my settings:
<key>VMOptions</key>
 <array>
 <string>-Xms250M</string>
 <string>-Xmx2048M</string>
 <string>-XX:MaxPermSize=512m</string>
 </array>

Save the changes that you’ve made and restart Protege for these to take effect.

This principle also applies to the Protege server. If you have not already, update the ‘run_protege_server.bat’ / ‘run_protege_server.sh’ file to increase the maximum memory JVM option as follows by setting the -Xmx parameter:

For Unix / Mac / Linux:

MAX_MEMORY=-Xmx2048M -XX:MaxPermSize=512m

On 64-bit Windows platforms (with the 64-bit Java installation):

set MAX_MEMORY=-Xmx2048M

On 32-bit JVMs on 64/32-bit Windows, there’s a limit to how much memory can be allocated:

set MAX_MEMORY=-Xmx1536M

 

Tomcat / Essential Viewer / Essential Import Utility

The memory settings for the Tomcat that is running the Essential Viewer should also be set to around 2GB for 64-bit Java environments.

On Windows

If you are running Tomcat as a Windows service, you can set the upper memory limit using the tomcat8w.exe program. You’ll find this either in the start menu or in the install folder of Tomcat. This will pop-up a configuration panel.

  • Select the ‘Java’ tab and then set the parameter for the Maximum memory pool to 2048
  • Click Apply
  • restart Tomcat for these settings to take effect.

On Mac

If running the Viewer Tomcat on a Mac / Linux platform, you can set these using the ‘sentenv.sh’ file in <TOMCAT INSTALL>/bin and set the CATALINA_OPTS variable, e.g.:

export CATALINA_OPTS=”-Xms128m -Xmx2048m -XX:MaxPermSize=512m”
export JAVA_OPTS=”-Djava.awt.headless=true”

If this file doesn’t exist then simply create a new text file and save it as setenv.sh with these lines in it.

Again, you must restart Tomcat for these settings to take effect.
 

Troubleshooting

If things aren’t working as expected, then the Log files are your friends. The Protege log is in the Protege install folder under logs and is called protege_###.log. The Tomcat log is in the Tomcat install folder under logs and is called catalina.out. What you’re looking for is anything that mention “memory” or “heap”. If you’re seeing these errors then you haven’t properly configured the settings.

As always, you can post your questions on the Essential Forums at http://enterprise-architecture.org/forums and we’ll answer as quickly as we can. Don’t forget to use the search too as there are over five years of posts and there’s a good chance your question has been answered before.

Once you’ve got these settings right, you should have many years of stability and performance from your Essential Install. If you’re still having problems though and would like some professional support then contact EAS via the Services menu for more information on how we can help.

Do I have to use Tomcat to use Essential?

The Essential Project takes advantage of a number of free, open-source components, including Apache Tomcat. However, do you have to use Tomcat to use Essential Architecture Manager?

This is a question that we realise potential users of the Essential Project tools are asking. In particular when the architecture team has spent many years trying to get to grips with technology diversity, it can be somewhat embarrassing – or even not an option – to have to go off-piste to use an enterprise architecture management tool!

The simple answer to this question is, however, “no”.

You do not have to use Apache Tomcat to use Essential Architecture Manager.

From the outset, we designed the Essential Architecture Manager software so that it can run on any platform – both operating system and application server – to provide as much flexibility in the prerequisites as possible. This means that Essential can fit into as many existing technology architectures as possible, taking advantage of existing technology platforms wherever possible.

The same question can be posed to the choice of relational database software for multi-user installations. Again, as we can see from the software architecture model, where a range of JDBC-compliant databases can be used, Essential can fit into your existing technology architecture, taking advantage of your standard database platform.

Essential Architecture Manager Software Architecture
Essential Architecture Manager Software Architecture

If I don’t have to use Apache Tomcat, what else can I use?

You can use any Java Servlet engine or J2EE application server as the runtime platform for Essential Viewer, which is packaged as a standard Java WAR file. This gives you the freedom to deploy and run Essential Viewer on a range of application servers such as Oracle AS, IBM WebSphere or JBoss.

Since the Essential Project is a free, open-source toolset, we have focussed on application servers and database platforms that are also available free and open-source. The available documentation covers these free platforms as we find that most of our users – certainly the initial stages of using Essential – use these platforms. However, in the spirit of open-source and applying this to our documentation we would welcome any documentation contributions from users who have experience to share about deploying the Essential Viewer WAR to alternative Java application servers.

What about the installer?

The Essential Project takes advantage of a number of other open-source toolkits and the installation process involves adding plugins or components to these other open source tools, e.g. Protege and Tomcat. The first releases of Essential did not include an automated installer but we provided detailed documentation for the installation process – including troubleshooting – and this documentation is applicable to other Java application servers.

In order to make the installation process as simple as possible, the automated installer checks the locations of the Protege and Application Server that you specify to help ensure that the Essential components are being installed in the correct places. Although the installer does not assume that Tomcat is being used (despite the messages on the installer windows!), it does assume that the target application server holds its web applications in a folder called ‘webapps’ – which is what Tomcat does.

This means that if the installer cannot find a folder called webapps in the location that you’ve specified for the Application Server, the installer will not proceed.

It is not really practical to cover all the variations of Application Server deployment approaches, so currently a work-around for anyone who is not using Tomcat is to create a ‘webapps’ folder in your Application Server and install the Essential Viewer WAR to there.

Perhaps the other approach is to relax the error-checking in the installer and allow the Essential Viewer WAR to be installed to any folder on the target environment? This places more responsibility on the user of the installer to install the WAR to the correct location but also provides them with more flexibility.

Either way, if you have any problems installing any of the Essential Project components, please contact us. Free support is always available through the forums.

I would be very interested to hear any views on the how to strike this balance in the installer.