Installing OpenBoxes on Ubuntu 16.04

1. Check Requirements

System Requirements

  • Internet connection (recommended)
  • 2GB RAM (minimum)
  • 25GB disk storage (minimum)

Software Requirements

  • Ubuntu 16.04 LTS
  • Java 7
  • Tomcat 7
  • MySQL 5.7+
  • SMTP service

2. Choose where to install

Whether you plan to install OpenBoxes on-premise or in the cloud, the installation instructions should be the same. However, getting to a place


Here are a few options for cheapish cloud hosting providers.

Hosting Provider Instance Type Monthly Cost
Digital Ocean droplet Droplet 2GB $10
Amazon Web Services EC2 t2.small 2GB $20
Google Compute Engine g1-small 1.7GB $20
RimuHosting Customizable VPS $20
Linode Linode 2GB $10

NOTE: AWS has a free-tier that includes a free year of 750 hours per month for t2.micro EC2 instances (as well as other services). It's a great deal it if you're not going to be using OpenBoxes too heavily. Unfortunately, keeping a Java-based web application like OpenBoxes happy on a t2.micro (1GB of RAM) is not easy. You may need to reduce the heap size and perm generation memory allocated to Tomcat to something minimal (see step 5 for more details).


Installing OpenBoxes on-premise requires a bit of work to install the appropriate Ubuntu version on the rack-mounted server, desktop, or laptop that you've designated as your server. Our installation docs will not describe how to install Ubuntu 16.04 Desktop or Server, so you'll need to consult Ubuntu docs. Here are a few tutorials that might be helpful.

3. Install dependencies

3.1 Update package information

sudo apt-get update

3.2 Upgrade packages already installed

sudo apt-get upgrade

3.3 Install Java 7

You must install a Java 7 JRE/JDK. Unfortunately, the APT Repository on Ubuntu 16.04 does not include a version of the Java 7 JRE or JDK so we'll need to do some work to get this working. I would personally recommend Option 2 below.


For the time being, you MUST use Java 7! The version of Grails that we're using does not support Java 8+ or beyond. We are working on upgrading to the latest version of Grails, but we're still several months away from completing that migration.


In case it wasn't clear from the box above this means you should NOT attempt to install the default-jre, openjdk-8-jre, or openjdk-9-jre packages from the APT repository.

Grails 1.3.9 does not support Java 8+ so Tomcat will fail to deploy OpenBoxes. When it fails, you will send an email to asking why the installation failed. When we receive your email, we will point you back to the little blue box that you ignored. Don't be that person.

Choose your choice

See the following StackExchange question for more details

  • Option 1: Manual Installation (not recommended) You can certainly use this solution, but I had some trouble getting it to work so I would not recommend it. See

  • Option 2: Automatic Installation (recommended) I would recommend this solution. It's a little more complex but seems to behave as you'd expect when installing from the APT repository.

  • Option 3: Oracle Java (not not recommended)1 This would probably be a recommended option, but Oracle ended public support for JDK 7 along time ago.

  • Option 4: Install from Zulu Linux (not not recommended)1 This seems like an ok option if you're comfortable manually install Debian packages - it's pretty straightforward.

  • Option 5: Install from an unsupported package maintainer (not recommended) This is probably the easiest solution, but also the least secure. Your friends will call you names.

  • Option 6: Use docker (recommended) I would recommend using docker, but unfortunately do not have any instructions to share at this time.


Do not use Option 5 in production. Do not use this solution unless you are in a rush and either plan to do it properly when you have time or you plan to throw away this server after evaluating OpenBoxes.

Configure Java version

$ sudo update-alternatives --config java
There is only one alternative in link group java (providing /usr/bin/java): /usr/lib/jvm/java-7-openjdk-amd64/jre/bin/java
Nothing to configure.

Check Java version

Make sure you see something like java version 1.7.0_xyz.

$ java -version
java version "1.7.0_161"
OpenJDK Runtime Environment (IcedTea 2.6.12) (7u161-2.6.12-1)
OpenJDK 64-Bit Server VM (build 24.161-b01, mixed mode)

3.4 Tomcat

Install Tomcat 7

Because we're using Java 7, we need to install a version of Tomcat that has been compiled with Java 7. Otherwise, you'll encounter the following error when deploying OpenBoxes.

2018-10-31 12:44:45,463 [localhost-startStop-1] INFO  xml.XmlBeanDefinitionReader  - Loading XML bean definitions from ServletContext resource [/WEB-INF/applicationContext.xml]
2018-10-31 12:44:46,299 [localhost-startStop-1] ERROR context.ContextLoader  - Context initialization failed
org.springframework.beans.factory.access.BootstrapException: Error executing bootstraps; nested exception is java.lang.NoSuchMethodError: java.util.concurrent.ConcurrentHashMap.keySet()Ljava/util/concurrent/ConcurrentHashMap$KeySetView;
  at org.codehaus.groovy.grails.web.context.GrailsContextLoader.createWebApplicationContext(
  at org.springframework.web.context.ContextLoader.initWebApplicationContext(
  at org.springframework.web.context.ContextLoaderListener.contextInitialized(
  at org.apache.catalina.core.StandardContext.listenerStart(
  at org.apache.catalina.core.StandardContext.startInternal(
  at org.apache.catalina.util.LifecycleBase.start(
  at org.apache.catalina.core.ContainerBase.addChildInternal(
  at org.apache.catalina.core.ContainerBase.addChild(
  at org.apache.catalina.core.StandardHost.addChild(
  at org.apache.catalina.startup.HostConfig.deployWAR(
  at org.apache.catalina.startup.HostConfig$
  at java.util.concurrent.Executors$
  at java.util.concurrent.ThreadPoolExecutor.runWorker(
  at java.util.concurrent.ThreadPoolExecutor$


Tomcat 7 in the APT repository was compiled with Java 8, which causes the aforementioned error during deployment.


Getting Started

  • Go to the Tomcat Downloads page
  • Choose a mirror (or leave the default)
  • Right-click on the Core tar.gz link (paste in step 3 below)

Download and unpack

$ sudo mkdir /opt/tomcat
$ cd /opt/tomcat
$ sudo wget
$ sudo tar xvzf apache-tomcat-7.0.91.tar.gz

Create user, group and change permissions

$ sudo groupadd tomcat
$ sudo useradd -s /bin/false -g tomcat -d /opt/tomcat tomcat 
$ cd apache-tomcat-7.0.91
$ sudo chgrp -R tomcat /opt/tomcat
$ sudo chown -R tomcat:tomcat /opt/tomcat
$ sudo chown -R tomcat webapps/ work/ temp/ logs/ conf/

Create service

sudo vi /etc/systemd/system/tomcat.service


Description=Apache Tomcat Web Application Container


Environment='CATALINA_OPTS=-Xms512m -Xmx512m -server -XX:+UseParallelGC'





You will likely encounter OutOfMemoryErrors with Tomcat's default memory settings.

You may be able to get away with using 256m as the max heap size, but 512m is a good setting, even for production environments. Using more memory will allow you to cache more data, but does not always result in a better performing application. So there's no need in getting carried away. We've been using about 1024m in production for over a year and that suits us fine.

If you are in a limited memory environment (like an EC2 t2.micro which only has 1GB of memory) you will need to reduce your memory settings a little more.

Environment='CATALINA_OPTS=-Xms128m -Xmx256m -XX:MaxPermSize=128m -server -XX:+UseParallelGC'

Unfortunately, with so little memory allocated you will probably run into several types of OutOfMemoryError issues (see Troublshooting section below).

Register service

sudo systemctl daemon-reload

Start Tomcat

systemctl start tomcat

Systemctl commands

systemctl start tomcat
systemctl stop tomcat
systemctl status tomcat

Service wrapper

At this point I generally go back to using the Ubuntu's service wrapper which abstracts the underlying implementation (could be /etc/init.d, Upstart, or systemctl). But it's up to you whether you want to continue using systemctl or switch back to service.

Here are the commands available if using the service wrapper:

sudo service tomcat status
sudo service tomcat stop
sudo service tomcat start
sudo service tomcat restart

Configure Tomcat manager (optional)

This configuration can be used to make future upgrades through the Tomcat manager web interface. Make sure the file is only readable by root and/or the user that runs Tomcat. Replace and with appropriate values. See Tomcat docs for more information (


  <role rolename="manager-gui"/>
  <role rolename="manager-script"/>
  <role rolename="manager-jmx"/>
  <role rolename="manager-status"/>
  <user username="<GUI-USERNAME>" password="<GUI-PASSWORD>" roles="manager-gui"/>
  <user username="<SCRIPT-USERNAME>" password="<SCRIPT-PASSWORD>" roles="manager-script"/>

NOTE: Please don't use obvious passwords (i.e. tomcat, password, s3cret, etc) because your server will get exploited.

3.5 MySQL

Install MySQL Server

Install MySQL from the APT repository. Finally, something easy!

sudo apt-get install mysql-server


Remember the password you enter for the root user.

Configure MySQL Server

Allow external connections [optional]

If you need to allow external connections to MySQL then you'll need to edit the bind-address mysqld configuration. This is a security risk so please ensure that you set passwords and grant permissions in a way that does not leave you vulnerable to attacks.


# Instead of skip-networking the default is now to listen only on
# localhost which is more compatible and is not less secure.
#bind-address           =
bind-address            =


You may encounter an error when using the default mysql-server package (MySQL 5.7). The error (below) requires a configuration change within MySQL.

Expression #1 of SELECT list is not in GROUP BY clause and contains nonaggregated column 
'' which is not functionally dependent on columns in GROUP BY clause; this 
is incompatible with sql_mode=only_full_group_by

This error is caused by the fact that ONLY_FULL_GROUP_BY is enabled in MySQL 5.7 by default.

mysql> show variables like '%sql_mode%';
| Variable_name | Value                                                                                                                                     |
1 row in set (0.01 sec)

In order to this avoid error, please copy the sql_mode value above, remove the ONLY_FULL_GROUP_BY option and add it as a new line under the [mysqld] section within /etc/alternatives/my.cnf.



Eventually we plan to fix the bug, but for now the config change is recommended.

Restart MySQL

sudo service mysql restart

Create database

$ mysql -u root -p -e 'create database openboxes default charset utf8;'

Grant permissions to new new database user

mysql -u root -p -e 'grant all on openboxes.* to '<username>'@'localhost' identified by "<password>";'


For security reasons, you will want to set a good password. These values should be used in the dataSource.username and dataSource.password configuration properties in

3.6 Configure Environment

Determine the path to Java

$ sudo update-java-alternatives --list
java-1.7.0-openjdk-amd64       1071       /usr/lib/jvm/java-1.7.0-openjdk-amd64

Add environment variables to ~/.bashrc

export JAVA_HOME=/usr/lib/jvm/java-1.7.0-openjdk-amd64
export CATALINA_HOME=/opt/tomcat/apache-tomcat-7.0.91

Refresh environment

. ~/.bashrc

3.7 Configure application

Create file

cd /opt/tomcat
sudo mkdir /opt/tomcat/.grails
sudo vi /opt/tomcat/.grails/

Copy the following contents into


# Database connection settings

# Example of a simple JDBC URL (not to be used in production)

# Example of a more complex JDBC URL (used in our ccurent production environment)

# Used primarily with g:link when absoluteUrl is true (e.g. links in emails)

# OpenBoxes mail settings - disabled by default (unless you set up an SMTP server)


Change dataSource.username and dataSource.password to the username and password you set in the grant all command above.


Change grails.serverURL to the IP address or domain name you plan to use for your server.


Documentation for all available configuration properties is provided in the Configuration section.

3.8 Deployment

Stop tomcat

$ sudo service tomcat stop

Download latest release

  1. Go to the the latest release page on GitHub.
  2. Right-click on openboxes.war
  3. Select Copy link address
  4. Paste the link address in the following command
$ sudo wget<version>/openboxes.war

Copy WAR file to webapps

$ sudo cp openboxes.war /opt/tomcat/apache-tomcat-7.0.91/webapps/openboxes.war

Change file ownership

$ sudo chown tomcat:tomcat /opt/tomcat/apache-tomcat-7.0.91/webapps/openboxes.war

Restart Tomcat

$ sudo service tomcat start

Watch Tomcat logs

The deployment will take about 10-20 minutes the first time because the application needs to perform hundreds of database migrations. Keep an eye out for any errors/exceptions that pop up in the catalina.out log file and check the Troubleshooting section for details on how to handle these issues.

$ sudo tail -f /opt/tomcat/apache-tomcat-7.0.91/logs/catalina.out

3.9 Troubleshooting

Unable to load specified config location

You can ignore these errors because these files are only used to override the default

Using configuration locations [, classpath:openboxes-config.groovy, file:/opt/tomcat/.grails/, file:/opt/tomcat/.grails/openboxes-config.groovy] [production]
Unable to load specified config location : class path resource [] cannot be opened because it does not exist
Unable to load specified config location classpath:openboxes-config.groovy : class path resource [openboxes-config.groovy] cannot be opened because it does not exist
Unable to load specified config location file:/opt/tomcat/.grails/openboxes-config.groovy : /opt/tomcat/.grails/openboxes-config.groovy (No such file or directory)

However, if the log shows that the following file could not be found, then we might have a problem. Check that the file exists and that the ownership and permissions on this file allow the tomcat user to read it.

Unable to load specified config location file:/opt/tomcat/.grails/ : /opt/tomcat/.grails/ (No such file or directory)

Java OutOfMemoryError

The following errors are related to the -Xms (min heap), -Xmx (max heap) , and -XX:MaxPermSize=256m (max perm gen space) memory settings. These errors indicate that the heap / permgen memory spaces are not allocated appropriately and/or there's a memory leak in the application.

  • Heap space (OutOfMemoryError: Java heap space)
  • PermGen (OutOfMemoryError: PermGen space)

See [this article] ( for a good description of the problem. Contact if you have further questions.

Out of Memory: Killed process 31088 (java)

In this case, the Linux kernel has killed your Tomcat instance because it over stepped the OS bounds on memory. At this point, you may have increased the max heap size as much as you can. This probably means you need to upgrade to a larger instance type (i.e. as we mentioned above, an instance type that has 2GB of memory is a good start). stacktrace.log (Permission denied)

You can safely ignore this error.

log4j:ERROR setFile(null,true) call failed. stacktrace.log (Permission denied)
    at Method)
    at org.apache.log4j.FileAppender.setFile(
    at org.apache.log4j.FileAppender.activateOptions(
    at org.apache.log4j.spi.OptionHandler$ Source)
    at org.codehaus.groovy.runtime.callsite.CallSiteArray.defaultCall(
    at org.codehaus.groovy.grails.plugins.logging.Log4jConfig.createFullstackTraceAppender(Log4jConfig.groovy:177)
    at org.codehaus.groovy.grails.plugins.logging.Log4jConfig.this$2$createFullstackTraceAppender(Log4jConfig.groovy)
    at org.codehaus.groovy.grails.plugins.logging.Log4jConfig$this$2$createFullstackTraceAppender.callCurrent(Unknown Source)
    at org.codehaus.groovy.runtime.callsite.CallSiteArray.defaultCallCurrent(
    at org.codehaus.groovy.runtime.callsite.AbstractCallSite.callCurrent(
    at org.codehaus.groovy.runtime.callsite.AbstractCallSite.callCurrent(
    at org.codehaus.groovy.grails.plugins.logging.Log4jConfig.configure(Log4jConfig.groovy:145)
    at org.codehaus.groovy.grails.web.util.Log4jConfigListener.contextInitialized(
    at org.apache.catalina.core.StandardContext.listenerStart(
    at org.apache.catalina.core.StandardContext.startInternal(
    at org.apache.catalina.util.LifecycleBase.start(
    at org.apache.catalina.core.ContainerBase.addChildInternal(
    at org.apache.catalina.core.ContainerBase.addChild(
    at org.apache.catalina.core.StandardHost.addChild(
    at org.apache.catalina.startup.HostConfig.deployWAR(
    at org.apache.catalina.startup.HostConfig$
    at java.util.concurrent.Executors$
    at java.util.concurrent.ThreadPoolExecutor.runWorker(
    at java.util.concurrent.ThreadPoolExecutor$

Could not connect to SMTP host: localhost, port: 25;

By default, the system assumes that there's an SMTP server listening on port 25 so that it can send exceptions to This should probably be disabled by default. For now you can just ignore these errors.

javax.mail.MessagingException: Could not connect to SMTP host: localhost, port: 25;
  nested exception is: Connection refused (Connection refused)

MySQLSyntaxErrorException: Unknown column 'this_.created_by_id' in 'field list'

This is related to a bug / limitation with the Quartz scheduler. By default we can only limit the Quartz scheduler from starting tasks for up to X seconds. We cannot set dependencies such as "when the database has been created". Because of this limitation, the Quartz scheduler triggers all jobs during the application bootstrapping and before the database migrations have been completed. Therefore, some Quartz jobs which depend on the database are executed before the database is ready. Hence the "Unknown column" errors.

Related issues:

Caused by: com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException: Unknown column 'this_.created_by_id' in 'field list'
    at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
    at sun.reflect.NativeConstructorAccessorImpl.newInstance(
    at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(
    at java.lang.reflect.Constructor.newInstance(
    at com.mysql.jdbc.Util.handleNewInstance(
    at com.mysql.jdbc.Util.getInstance(
    at com.mysql.jdbc.SQLError.createSQLException(
    at com.mysql.jdbc.MysqlIO.checkErrorPacket(
    at com.mysql.jdbc.MysqlIO.checkErrorPacket(
    at com.mysql.jdbc.MysqlIO.sendCommand(
    at com.mysql.jdbc.MysqlIO.sqlQueryDirect(
    at com.mysql.jdbc.ConnectionImpl.execSQL(
    at com.mysql.jdbc.PreparedStatement.executeInternal(
    at com.mysql.jdbc.PreparedStatement.executeQuery(
    at com.mchange.v2.c3p0.impl.NewProxyPreparedStatement.executeQuery(
    at org.hibernate.jdbc.AbstractBatcher.getResultSet(
    at org.hibernate.loader.Loader.getResultSet(
    at org.hibernate.loader.Loader.doQuery(
    at org.hibernate.loader.Loader.doQueryAndInitializeNonLazyCollections(
    at org.hibernate.loader.Loader.doList(
    ... 75 more

Once the database migration process has completed you should stop seeing these errors and the logs will show that the deployment has completed successfully.

2018-11-16 18:11:25,783 [localhost-startStop-1] INFO  liquibase  - Release Database Lock
2018-11-16 18:11:25,784 [localhost-startStop-1] INFO  liquibase  - Successfully released change log lock
2018-11-16 18:11:26,583 [localhost-startStop-1] INFO  bootstrap.BootStrap  - Finished running liquibase changelog(s)!
2018-11-16 18:11:26,584 [localhost-startStop-1] INFO  bootstrap.BootStrap  - Insert test fixtures?  true
2018-11-16 18:11:26,585 [localhost-startStop-1] INFO  bootstrap.BootStrap  - Inserting test fixtures ...
2018-11-16 18:11:26,598 [localhost-startStop-1] INFO  bootstrap.BootStrap  - Creating uploads directory if it doesn't already exist
2018-11-16 18:11:26,598 [localhost-startStop-1] INFO  context.ContextLoader  - Root WebApplicationContext: initialization completed in 523311 ms
Nov 16, 2018 6:11:26 PM org.apache.catalina.startup.HostConfig deployWAR
INFO: Deployment of web application archive /opt/tomcat/apache-tomcat-7.0.91/webapps/openboxes.war has finished in 545,140 ms
Nov 16, 2018 6:11:27 PM org.apache.coyote.AbstractProtocol start
INFO: Starting ProtocolHandler ["http-bio-8080"]
Nov 16, 2018 6:11:27 PM org.apache.coyote.AbstractProtocol start
INFO: Starting ProtocolHandler ["ajp-bio-8009"]
Nov 16, 2018 6:11:27 PM org.apache.catalina.startup.Catalina start
INFO: Server startup in 546085 ms

  1. You read that correctly. I wrote "not not recommended", which is a double negative meaning "we're not recommending it, but we're also not not recommending it."