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:
- Start Protege. Go to File->Preferences->Protege.lax
- Update the row for the property ‘lax.nl.java.option.java.heap.size.max’
- This is set in bytes, so set this to 2048000000 for installs with the 64-bit Java environment.
- Click OK
- 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.
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.